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.
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 @@
## 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 @@
| 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 @@
# 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 @@
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 @@
return rule(
impl,
+ doc = doc,
attrs = attrs,
fragments = fragments,
test = True,
