Add more situations to the angle bracket test.

Co-authored-by: Adam Azarchs <[email protected]>

test/testdata/angle_bracket_test/golden.md

@@ -2,23 +2,35 @@
 
 Input file to test angle bracket bug (https://github.com/bazelbuild/skydoc/issues/186)
 
+See https://github.com/bazelbuild/skydoc/issues/186,
+https://github.com/bazelbuild/stardoc/issues/132,
+and https://github.com/bazelbuild/stardoc/issues/137.
+
+<b>HTML formatting</b> can be used in docstrings, just as in regular Markdown.
+Literal angle brackets can be obtained by escaping them with a backslash, where
+the backslash itself must be escaped for use in a Starlark docstring
+(`\\<` becomes \<), or by using HTML entities (`&lt;` becomes &lt;).
+Angle brackets are also preserved in inline code blocks (`#include <vector>`).
+
+
 <a id="my_anglebrac"></a>
 
 ## my_anglebrac
 
 <pre>
-my_anglebrac(<a href="#my_anglebrac-name">name</a>, <a href="#my_anglebrac-useless">useless</a>)
+my_anglebrac(<a href="#my_anglebrac-name">name</a>, <a href="#my_anglebrac-also_useless">also_useless</a>, <a href="#my_anglebrac-useless">useless</a>)
 </pre>
 
-Rule with <brackets>
+Rule with \<brackets>
 
 **ATTRIBUTES**
 
 
 | Name  | Description | Type | Mandatory | Default |
 | :------------- | :------------- | :------------- | :------------- | :------------- |
 | <a id="my_anglebrac-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
-| <a id="my_anglebrac-useless"></a>useless |  Args with some tags: &lt;tag1&gt;, &lt;tag2&gt;   | String | optional |  `"Find <brackets>"`  |
+| <a id="my_anglebrac-also_useless"></a>also_useless |  Args with some formatted tags: <code>&lt;tag&gt;</code>   | String | optional |  `"1<<5"`  |
+| <a id="my_anglebrac-useless"></a>useless |  Args with some tags: &lt;tag1&gt;, &lt;tag2&gt;   | String | optional |  `"Find \<brackets>"`  |
 
 
 <a id="bracketuse"></a>
@@ -29,7 +41,7 @@ Rule with <brackets>
 bracketuse(<a href="#bracketuse-foo">foo</a>, <a href="#bracketuse-bar">bar</a>, <a href="#bracketuse-baz">baz</a>)
 </pre>
 
-Information with <brackets>
+Information with \<brackets>
 
 **FIELDS**
 
@@ -46,23 +58,69 @@ Information with <brackets>
 ## bracket_function
 
 <pre>
-bracket_function(<a href="#bracket_function-name">name</a>)
+bracket_function(<a href="#bracket_function-param">param</a>, <a href="#bracket_function-md_string">md_string</a>)
 </pre>
 
-Dummy docstring with <brackets>.
+Dummy docstring with \<brackets>.
+
+This rule runs checks on `<angle brackets>`.
 
-This rule runs checks on <angle brackets>.
+Sometimes, we have such things on their own, but they may
+also appear in code blocks, like
+
+```starlark
+foo = "<thing>"
+```
 
 
 **PARAMETERS**
 
 
 | Name  | Description | Default Value |
 | :------------- | :------------- | :------------- |
-| <a id="bracket_function-name"></a>name |  an arg with **formatted** docstring.   |  none |
+| <a id="bracket_function-param"></a>param |  an arg with **formatted** docstring, <code>&lt;default&gt;</code> by default.   |  `"<default>"` |
+| <a id="bracket_function-md_string"></a>md_string |  A markdown string.   |  `"foo `1<<10` bar"` |
 
 **RETURNS**
 
-some <angled> brackets
+some \<angled> brackets
+
+**DEPRECATED**
+
+deprecated for \<reasons> as well as `<reasons>`.
+
+
+<a id="bracket_aspect"></a>
+
+## bracket_aspect
+
+<pre>
+bracket_aspect(<a href="#bracket_aspect-name">name</a>, <a href="#bracket_aspect-brackets">brackets</a>)
+</pre>
+
+Aspect.
+
+Sometimes, we want a code block like
+```starlark
+foo = "<brackets>"
+```
+which includes angle brackets.
+
+
+**ASPECT ATTRIBUTES**
+
+
+| Name | Type |
+| :------------- | :------------- |
+| deps| String |
+
+
+**ATTRIBUTES**
+
+
+| Name  | Description | Type | Mandatory | Default |
+| :------------- | :------------- | :------------- | :------------- | :------------- |
+| <a id="bracket_aspect-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
+| <a id="bracket_aspect-brackets"></a>brackets |  Attribute with \&lt;brackets&gt;   | String | optional |  `"<default>"`  |
 
 

test/testdata/angle_bracket_test/input.bzl

@@ -1,23 +1,43 @@
-"""Input file to test angle bracket bug (https://github.com/bazelbuild/skydoc/issues/186)"""
+"""Input file to test angle bracket bug (https://github.com/bazelbuild/skydoc/issues/186)
 
-def bracket_function(name):
-    """Dummy docstring with <brackets>.
+See https://github.com/bazelbuild/skydoc/issues/186,
+https://github.com/bazelbuild/stardoc/issues/132,
+and https://github.com/bazelbuild/stardoc/issues/137.
 
-    This rule runs checks on <angle brackets>.
+<b>HTML formatting</b> can be used in docstrings, just as in regular Markdown.
+Literal angle brackets can be obtained by escaping them with a backslash, where
+the backslash itself must be escaped for use in a Starlark docstring
+(`\\\\<` becomes \\<), or by using HTML entities (`&lt;` becomes &lt;).
+Angle brackets are also preserved in inline code blocks (`#include <vector>`).
+"""
+
+def bracket_function(param = "<default>", md_string = "foo `1<<10` bar"):
+    """Dummy docstring with \\<brackets>.
+
+    This rule runs checks on `<angle brackets>`.
+
+    Sometimes, we have such things on their own, but they may
+    also appear in code blocks, like
+
+    ```starlark
+    foo = "<thing>"
+    ```
 
     Args:
-        name: an arg with **formatted** docstring.
+        param: an arg with **formatted** docstring, `<default>` by default.
+        md_string: A markdown string.
 
     Returns:
-        some <angled> brackets
+        some \\<angled> brackets
 
+    Deprecated:
+        deprecated for \\<reasons> as well as `<reasons>`.
     """
-    _ignore = name  # @unused
-    pass
+    return param or md_string
 
 # buildifier: disable=unsorted-dict-items
 bracketuse = provider(
-    doc = "Information with <brackets>",
+    doc = "Information with \\<brackets>",
     fields = {
         "foo": "A string representing <foo>",
         "bar": "A string representing bar",
@@ -31,11 +51,38 @@ def _rule_impl(ctx):
 
 my_anglebrac = rule(
     implementation = _rule_impl,
-    doc = "Rule with <brackets>",
+    doc = "Rule with \\<brackets>",
     attrs = {
         "useless": attr.string(
             doc = "Args with some tags: <tag1>, <tag2>",
-            default = "Find <brackets>",
+            default = "Find \\<brackets>",
+        ),
+        "also_useless": attr.string(
+            doc = "Args with some formatted tags: `<tag>`",
+            default = "1<<5",
+        ),
+    },
+)
+
+def _bracket_aspect_impl(ctx):
+    _ignore = [ctx]  # @unused
+    return []
+
+bracket_aspect = aspect(
+    implementation = _bracket_aspect_impl,
+    doc = """Aspect.
+
+Sometimes, we want a code block like
+```starlark
+foo = "<brackets>"
+```
+which includes angle brackets.
+""",
+    attr_aspects = ["deps"],
+    attrs = {
+        "brackets": attr.string(
+            doc = "Attribute with \\<brackets>",
+            default = "<default>",
         ),
     },
 )