From e3361ec7913ea306913862574aa02165fba56211 Mon Sep 17 00:00:00 2001 From: Adam Azarchs Date: Tue, 11 Oct 2022 12:45:03 -0700 Subject: [PATCH] Add more situations to the angle bracket test. Examples to demonstrate https://github.com/bazelbuild/stardoc/issues/137. --- test/testdata/angle_bracket_test/golden.md | 62 ++++++++++++++++++++-- test/testdata/angle_bracket_test/input.bzl | 55 +++++++++++++++++-- 2 files changed, 109 insertions(+), 8 deletions(-) diff --git a/test/testdata/angle_bracket_test/golden.md b/test/testdata/angle_bracket_test/golden.md index a9619654..82059661 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. + + need to be escaped in some contexts. +They also need to _not_ be escaped when they're enclosed +in a ``. + + ## 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,23 +56,69 @@ Information with ## bracket_function 
-bracket_function(name)
+bracket_function(param, md_string)
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 = "" +``` + **PARAMETERS** | 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. | `"`1<<10`"` | **RETURNS** 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..5fa8c5b8 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): +See https://github.com/bazelbuild/skydoc/issues/186, +https://github.com/bazelbuild/stardoc/issues/132, +and https://github.com/bazelbuild/stardoc/issues/137. + + need to be escaped in some contexts. +They also need to _not_ be escaped when they're enclosed +in a ``. +""" + +def bracket_function(param = "", md_string = "`1<<10`"): """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 + 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 = "", + ), }, )