diff --git a/test/testdata/angle_bracket_test/golden.md b/test/testdata/angle_bracket_test/golden.md index a9619654..1cc82f5c 100755 --- a/test/testdata/angle_bracket_test/golden.md +++ b/test/testdata/angle_bracket_test/golden.md @@ -2,12 +2,21 @@ 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. + +HTML formatting can be used in docstrings, just as in regular Markdown. +Literal angle brackets can be obtained by escaping them with an (escaped) +backslash (`\\<` becomes \<) or via inline code blocks (`#include `). + + ## my_anglebrac
-my_anglebrac(name, useless)
+my_anglebrac(name, also_useless, useless)
 
Rule with @@ -18,6 +27,7 @@ Rule with | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | +| also_useless | Args with some formatted tags: <tag> | String | optional | `"1<<5"` | | useless | Args with some tags: <tag1>, <tag2> | String | optional | `"Find "` | @@ -46,12 +56,19 @@ Information with ## bracket_function
-bracket_function(name)
+bracket_function(param, md_string)
 
-Dummy docstring with . +Dummy docstring with \. + +This rule runs checks on ``. -This rule runs checks on . +Sometimes, we have such things on their own, but they may +also appear in code blocks, like + +```starlark +foo = "" +``` **PARAMETERS** @@ -59,10 +76,49 @@ This rule runs checks on . | Name | Description | Default Value | | :------------- | :------------- | :------------- | -| name | an arg with **formatted** docstring. | none | +| param | an arg with **formatted** docstring, <default> by default. | `""` | +| md_string | A markdown string. | `"foo `1<<10` bar"` | **RETURNS** -some brackets +some \ brackets + +**DEPRECATED** + +deprecated for \ as well as ``. + + + + +## bracket_aspect + +
+bracket_aspect(name, brackets)
+
+ +Aspect. + +Sometimes, we want a code block like +```starlark +foo = "" +``` +which includes angle brackets. + + +**ASPECT ATTRIBUTES** + + +| Name | Type | +| :------------- | :------------- | +| deps| String | + + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| name | A unique name for this target. | Name | required | | +| brackets | Attribute with \<brackets> | String | optional | `""""` | diff --git a/test/testdata/angle_bracket_test/input.bzl b/test/testdata/angle_bracket_test/input.bzl index 69daa7a8..dcf16f85 100644 --- a/test/testdata/angle_bracket_test/input.bzl +++ b/test/testdata/angle_bracket_test/input.bzl @@ -1,19 +1,37 @@ -"""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 . +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 . +HTML formatting can be used in docstrings, just as in regular Markdown. +Literal angle brackets can be obtained by escaping them with an (escaped) +backslash (`\\\\<` becomes \\<) or via inline code blocks (`#include `). +""" + +def bracket_function(param = "", md_string = "foo `1<<10` bar"): + """Dummy docstring with \\. + + This rule runs checks on ``. + + Sometimes, we have such things on their own, but they may + also appear in code blocks, like + + ```starlark + foo = "" + ``` Args: - name: an arg with **formatted** docstring. + param: an arg with **formatted** docstring, `` by default. + md_string: A markdown string. Returns: - some brackets + some \\ brackets + Deprecated: + deprecated for \\ as well as ``. """ - _ignore = name # @unused - pass + return param or md_string # buildifier: disable=unsorted-dict-items bracketuse = provider( @@ -37,5 +55,32 @@ my_anglebrac = rule( doc = "Args with some tags: , ", default = "Find ", ), + "also_useless": attr.string( + doc = "Args with some formatted tags: ``", + 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 = "" +``` +which includes angle brackets. +""", + attr_aspects = ["deps"], + attrs = { + "brackets": attr.string( + doc = "Attribute with \\", + default = "\"\"", + ), }, )