Add doc for unittest_toolchain attrs

bazelbuild · Oct 4, 2021 · e6f188c · e6f188c
1 parent dba494d
commit e6f188c
Showing 1 changed file with 53 additions and 6 deletions.
diff --git a/lib/unittest.bzl b/lib/unittest.bzl
@@ -63,12 +63,59 @@ def _unittest_toolchain_impl(ctx):
 unittest_toolchain = rule(
     implementation = _unittest_toolchain_impl,
     attrs = {
-        "failure_templ": attr.string(mandatory = True),
-        "file_ext": attr.string(mandatory = True),
-        "join_on": attr.string(mandatory = True),
-        "success_templ": attr.string(mandatory = True),
-        "escape_chars_with": attr.string_dict(),
-        "escape_other_chars_with": attr.string(default = ""),
+        "failure_templ": attr.string(
+            mandatory = True,
+            doc = (
+                "Test script template with a single `%s`. That " +
+                "placeholder is replaced with the lines in the " +
+                "failure message joined with the string " +
+                "specified in `join_with`. The resulting script " +
+                "should print the failure message and exit with " +
+                "non-zero status."
+            ),
+        ),
+        "file_ext": attr.string(
+            mandatory = True,
+            doc = (
+                "File extension for test script, including leading dot."
+            ),
+        ),
+        "join_on": attr.string(
+            mandatory = True,
+            doc = (
+                "String used to join the lines in the failure " +
+                "message before including the resulting string " +
+                "in the script specified in `failure_templ`."
+            ),
+        ),
+        "success_templ": attr.string(
+            mandatory = True,
+            doc = (
+                "Test script generated when the test passes. " +
+                "Should exit with status 0."
+            ),
+        ),
+        "escape_chars_with": attr.string_dict(
+            doc = (
+                "Dictionary of characters that need escaping in " +
+                "test failure message to prefix appended to escape " +
+                "those characters. For example, " +
+                '`{"%": "%", ">": "^"}` would replace `%` with ' +
+                "`%%` and `>` with `^>` in the failure message " +
+                "before that is included in `success_templ`."
+            ),
+        ),
+        "escape_other_chars_with": attr.string(
+            default = "",
+            doc = (
+                "String to prefix every character in test failure " +
+                "message which is not a key in `escape_chars_with` " +
+                "before including that in `success_templ`. For " +
+                'example, `"\"` would prefix every character in ' +
+                "the failure message (except those in the keys of " +
+                "`escape_chars_with`) with `\\`."
+            ),
+        ),
     },
 )