From 2bc90bdf7dc9914d126cf8594c3838494fc00d19 Mon Sep 17 00:00:00 2001
From: UebelAndre <github@uebelandre.com>
Date: Thu, 10 Feb 2022 14:00:29 -0800
Subject: [PATCH] Allow unit test rules to be documented (#343)

I find it more ergonomic to add notes or a description about a test to a `doc` attribute, similar to other rules, vs a comment block above it or in the `impl` function docstring. Hopefully this can improve the readability of test rules.
---
 docs/unittest_doc.md | 3 ++-
 lib/unittest.bzl     | 3 +++
 2 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/docs/unittest_doc.md b/docs/unittest_doc.md
index fe885f2..754ea32 100755
--- a/docs/unittest_doc.md
+++ b/docs/unittest_doc.md
@@ -37,7 +37,7 @@ unittest_toolchain(<a href="#unittest_toolchain-name">name</a>, <a href="#unitte
 ## analysistest.make
 
 <pre>
-analysistest.make(<a href="#analysistest.make-impl">impl</a>, <a href="#analysistest.make-expect_failure">expect_failure</a>, <a href="#analysistest.make-attrs">attrs</a>, <a href="#analysistest.make-fragments">fragments</a>, <a href="#analysistest.make-config_settings">config_settings</a>,
+analysistest.make(<a href="#analysistest.make-impl">impl</a>, <a href="#analysistest.make-doc">doc</a>, <a href="#analysistest.make-expect_failure">expect_failure</a>, <a href="#analysistest.make-attrs">attrs</a>, <a href="#analysistest.make-fragments">fragments</a>, <a href="#analysistest.make-config_settings">config_settings</a>,
                   <a href="#analysistest.make-extra_target_under_test_aspects">extra_target_under_test_aspects</a>)
 </pre>
 
@@ -73,6 +73,7 @@ Recall that names of test rules must end in `_test`.
 | Name  | Description | Default Value |
 | :------------- | :------------- | :------------- |
 | <a id="analysistest.make-impl"></a>impl |  The implementation function of the unit test.   |  none |
+| <a id="analysistest.make-doc"></a>doc |  A description of the rule that can be extracted by documentation generating tools.   |  <code>""</code> |
 | <a id="analysistest.make-expect_failure"></a>expect_failure |  If true, the analysis test will expect the target_under_test to fail. Assertions can be made on the underlying failure using asserts.expect_failure   |  <code>False</code> |
 | <a id="analysistest.make-attrs"></a>attrs |  An optional dictionary to supplement the attrs passed to the unit test's <code>rule()</code> constructor.   |  <code>{}</code> |
 | <a id="analysistest.make-fragments"></a>fragments |  An optional list of fragment names that can be used to give rules access to language-specific parts of configuration.   |  <code>[]</code> |
diff --git a/lib/unittest.bzl b/lib/unittest.bzl
index feea621..519720c 100644
--- a/lib/unittest.bzl
+++ b/lib/unittest.bzl
@@ -206,6 +206,7 @@ _action_retrieving_aspect = aspect(
 # TODO(cparsons): Provide more full documentation on analysis testing in README.
 def _make_analysis_test(
         impl,
+        doc = "",
         expect_failure = False,
         attrs = {},
         fragments = [],
@@ -238,6 +239,7 @@ def _make_analysis_test(
 
     Args:
       impl: The implementation function of the unit test.
+      doc: A description of the rule that can be extracted by documentation generating tools.
       expect_failure: If true, the analysis test will expect the target_under_test
           to fail. Assertions can be made on the underlying failure using asserts.expect_failure
       attrs: An optional dictionary to supplement the attrs passed to the
@@ -277,6 +279,7 @@ def _make_analysis_test(
 
     return rule(
         impl,
+        doc = doc,
         attrs = attrs,
         fragments = fragments,
         test = True,