Fix <angle bracket> escaping in more places (bazelbuild#133)

Specifically, we were failing to escape <brackets> in:
* module docstrings;
* function docstrings, including args, returns, and deprecated sections;
* provider docs & provider field default values;
* rule docs & rule attr default values;
* aspect docs & aspect attr default values.

(We had also failed to format rule and aspect attr default values in `<code>` tags.)

Tests have been updated accordingly.

Fixes bazelbuild#132.

docs/stardoc_rule.md

@@ -23,18 +23,18 @@ This rule is an experimental replacement for the existing skylark_doc rule.
 | Name  | Description | Type | Mandatory | Default |
 | :------------- | :------------- | :------------- | :------------- | :------------- |
 | <a id="stardoc-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
-| <a id="stardoc-aspect_template"></a>aspect_template |  The input file template for generating documentation of aspects.   | <a href="https://bazel.build/concepts/labels">Label</a> | optional | //stardoc:templates/markdown_tables/aspect.vm |
-| <a id="stardoc-deps"></a>deps |  A list of bzl_library dependencies which the input depends on.   | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | [] |
-| <a id="stardoc-format"></a>format |  The format of the output file. Valid values: 'markdown' or 'proto'.   | String | optional | "markdown" |
-| <a id="stardoc-func_template"></a>func_template |  The input file template for generating documentation of functions.   | <a href="https://bazel.build/concepts/labels">Label</a> | optional | //stardoc:templates/markdown_tables/func.vm |
-| <a id="stardoc-header_template"></a>header_template |  The input file template for the header of the output documentation.   | <a href="https://bazel.build/concepts/labels">Label</a> | optional | //stardoc:templates/markdown_tables/header.vm |
-| <a id="stardoc-input"></a>input |  The starlark file to generate documentation for.   | <a href="https://bazel.build/concepts/labels">Label</a> | optional | None |
+| <a id="stardoc-aspect_template"></a>aspect_template |  The input file template for generating documentation of aspects.   | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>//stardoc:templates/markdown_tables/aspect.vm</code> |
+| <a id="stardoc-deps"></a>deps |  A list of bzl_library dependencies which the input depends on.   | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> |
+| <a id="stardoc-format"></a>format |  The format of the output file. Valid values: 'markdown' or 'proto'.   | String | optional | <code>"markdown"</code> |
+| <a id="stardoc-func_template"></a>func_template |  The input file template for generating documentation of functions.   | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>//stardoc:templates/markdown_tables/func.vm</code> |
+| <a id="stardoc-header_template"></a>header_template |  The input file template for the header of the output documentation.   | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>//stardoc:templates/markdown_tables/header.vm</code> |
+| <a id="stardoc-input"></a>input |  The starlark file to generate documentation for.   | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>None</code> |
 | <a id="stardoc-out"></a>out |  The (markdown) file to which documentation will be output.   | <a href="https://bazel.build/concepts/labels">Label</a> | required |  |
-| <a id="stardoc-provider_template"></a>provider_template |  The input file template for generating documentation of providers.   | <a href="https://bazel.build/concepts/labels">Label</a> | optional | //stardoc:templates/markdown_tables/provider.vm |
-| <a id="stardoc-renderer"></a>renderer |  The location of the renderer tool.   | <a href="https://bazel.build/concepts/labels">Label</a> | optional | //stardoc:renderer |
-| <a id="stardoc-rule_template"></a>rule_template |  The input file template for generating documentation of rules.   | <a href="https://bazel.build/concepts/labels">Label</a> | optional | //stardoc:templates/markdown_tables/rule.vm |
-| <a id="stardoc-semantic_flags"></a>semantic_flags |  A list of canonical flags to affect Starlark semantics for the Starlark interpretter during documentation generation. This should only be used to maintain compatibility with non-default semantic flags required to use the given Starlark symbols.<br><br>For example, if <code>//foo:bar.bzl</code> does not build except when a user would specify <code>--incompatible_foo_semantic=false</code>, then this attribute should contain "--incompatible_foo_semantic=false".   | List of strings | optional | [] |
-| <a id="stardoc-stardoc"></a>stardoc |  The location of the stardoc tool.   | <a href="https://bazel.build/concepts/labels">Label</a> | optional | //stardoc:stardoc |
-| <a id="stardoc-symbol_names"></a>symbol_names |  A list of symbol names to generate documentation for. These should correspond to the names of rule definitions in the input file. If this list is empty, then documentation for all exported rule definitions will be generated.   | List of strings | optional | [] |
+| <a id="stardoc-provider_template"></a>provider_template |  The input file template for generating documentation of providers.   | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>//stardoc:templates/markdown_tables/provider.vm</code> |
+| <a id="stardoc-renderer"></a>renderer |  The location of the renderer tool.   | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>//stardoc:renderer</code> |
+| <a id="stardoc-rule_template"></a>rule_template |  The input file template for generating documentation of rules.   | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>//stardoc:templates/markdown_tables/rule.vm</code> |
+| <a id="stardoc-semantic_flags"></a>semantic_flags |  A list of canonical flags to affect Starlark semantics for the Starlark interpretter during documentation generation. This should only be used to maintain compatibility with non-default semantic flags required to use the given Starlark symbols.<br><br>For example, if <code>//foo:bar.bzl</code> does not build except when a user would specify <code>--incompatible_foo_semantic=false</code>, then this attribute should contain "--incompatible_foo_semantic=false".   | List of strings | optional | <code>[]</code> |
+| <a id="stardoc-stardoc"></a>stardoc |  The location of the stardoc tool.   | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>//stardoc:stardoc</code> |
+| <a id="stardoc-symbol_names"></a>symbol_names |  A list of symbol names to generate documentation for. These should correspond to the names of rule definitions in the input file. If this list is empty, then documentation for all exported rule definitions will be generated.   | List of strings | optional | <code>[]</code> |
 
 

stardoc/templates/markdown_tables/aspect.vm

@@ -6,7 +6,7 @@
 ${util.aspectSummary($aspectName, $aspectInfo)}
 </pre>
 
-$aspectInfo.getDocString()
+${util.htmlEscape($aspectInfo.getDocString())}
 
 **ASPECT ATTRIBUTES**
 
@@ -27,6 +27,6 @@ $aspectInfo.getDocString()
 | Name  | Description | Type | Mandatory | Default |
 | :------------- | :------------- | :------------- | :------------- | :------------- |
 #foreach ($attribute in $aspectInfo.getAttributeList())
-| <a id="${aspectName}-${attribute.name}"></a>$attribute.name | #if(!$attribute.docString.isEmpty()) ${util.markdownCellFormat($attribute.docString)} #else - #end  | ${util.attributeTypeString($attribute)} | ${util.mandatoryString($attribute)} |  $attribute.defaultValue |
+| <a id="${aspectName}-${attribute.name}"></a>$attribute.name | #if(!$attribute.docString.isEmpty()) ${util.markdownCellFormat($attribute.docString)} #else - #end  | ${util.attributeTypeString($attribute)} | ${util.mandatoryString($attribute)} | #if(!$attribute.defaultValue.isEmpty()) <code>${util.htmlEscape($attribute.defaultValue)}</code> #end  |
 #end
 #end

stardoc/templates/markdown_tables/func.vm

@@ -6,7 +6,7 @@
 ${util.funcSummary($funcInfo)}
 </pre>
 
-${funcInfo.docString}
+${util.htmlEscape($funcInfo.docString)}
 
 #if (!$funcInfo.getParameterList().isEmpty())
 **PARAMETERS**
@@ -15,18 +15,18 @@ ${funcInfo.docString}
 | Name  | Description | Default Value |
 | :------------- | :------------- | :------------- |
 #foreach ($param in $funcInfo.getParameterList())
-| <a id="${funcInfo.functionName}-${param.name}"></a>$param.name | #if(!$param.docString.isEmpty()) ${util.markdownCellFormat($param.docString)} #else <p align="center"> - </p> #end  | #if(!$param.getDefaultValue().isEmpty()) <code>$param.getDefaultValue()</code> #else none #end|
+| <a id="${funcInfo.functionName}-${param.name}"></a>$param.name | #if(!$param.docString.isEmpty()) ${util.markdownCellFormat($param.docString)} #else <p align="center"> - </p> #end  | #if(!$param.getDefaultValue().isEmpty()) <code>${util.htmlEscape($param.getDefaultValue())}</code> #else none #end|
 #end
 #end
 #if (!$funcInfo.getReturn().docString.isEmpty())
 
 **RETURNS**
 
-${funcInfo.getReturn().docString}
+${util.htmlEscape($funcInfo.getReturn().docString)}
 #end
 #if (!$funcInfo.getDeprecated().docString.isEmpty())
 
 **DEPRECATED**
 
-${funcInfo.getDeprecated().docString}
+${util.htmlEscape($funcInfo.getDeprecated().docString)}
 #end

stardoc/templates/markdown_tables/header.vm

@@ -1,3 +1,3 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
-${moduleDocstring}
+${util.htmlEscape($moduleDocstring)}

stardoc/templates/markdown_tables/provider.vm

@@ -6,7 +6,7 @@
 ${util.providerSummary($providerName, $providerInfo)}
 </pre>
 
-${providerInfo.docString}
+${util.htmlEscape($providerInfo.docString)}
 
 **FIELDS**
 

stardoc/templates/markdown_tables/rule.vm

@@ -6,7 +6,7 @@
 ${util.ruleSummary($ruleName, $ruleInfo)}
 </pre>
 
-${ruleInfo.docString}
+${util.htmlEscape($ruleInfo.docString)}
 
 **ATTRIBUTES**
 
@@ -15,6 +15,6 @@ ${ruleInfo.docString}
 | Name  | Description | Type | Mandatory | Default |
 | :------------- | :------------- | :------------- | :------------- | :------------- |
 #foreach ($attribute in $ruleInfo.getAttributeList())
-| <a id="${ruleName}-${attribute.name}"></a>$attribute.name | #if(!$attribute.docString.isEmpty()) ${util.markdownCellFormat($attribute.docString)} #else - #end  | ${util.attributeTypeString($attribute)} | ${util.mandatoryString($attribute)} | $attribute.defaultValue |
+| <a id="${ruleName}-${attribute.name}"></a>$attribute.name | #if(!$attribute.docString.isEmpty()) ${util.markdownCellFormat($attribute.docString)} #else - #end  | ${util.attributeTypeString($attribute)} | ${util.mandatoryString($attribute)} | #if(!$attribute.defaultValue.isEmpty())<code>${util.htmlEscape($attribute.defaultValue)}</code>#end |
 #end
 #end

test/testdata/android_basic_test/golden.md

@@ -19,7 +19,7 @@ This rule does android-related things.
 | :------------- | :------------- | :------------- | :------------- | :------------- |
 | <a id="android_related_rule-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
 | <a id="android_related_rule-first"></a>first |  -   | <a href="https://bazel.build/concepts/labels">Label</a> | required |  |
-| <a id="android_related_rule-fourth"></a>fourth |  -   | Boolean | optional | False |
+| <a id="android_related_rule-fourth"></a>fourth |  -   | Boolean | optional | <code>False</code> |
 | <a id="android_related_rule-second"></a>second |  -   | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required |  |
 | <a id="android_related_rule-third"></a>third |  -   | <a href="https://bazel.build/concepts/labels">Label</a> | required |  |
 

test/testdata/angle_bracket_test/golden.md

@@ -1,6 +1,9 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
-Input file to test angle bracket bug (https://github.com/bazelbuild/skydoc/issues/186)
+Input file to test &lt;angle bracket bugs&gt;
+
+See https://github.com/bazelbuild/skydoc/issues/186
+and https://github.com/bazelbuild/stardoc/issues/132
 
 <a id="my_anglebrac"></a>
 
@@ -10,15 +13,15 @@ Input file to test angle bracket bug (https://github.com/bazelbuild/skydoc/issue
 my_anglebrac(<a href="#my_anglebrac-name">name</a>, <a href="#my_anglebrac-useless">useless</a>)
 </pre>
 
-Rule with <brackets>
+Rule with &lt;brackets&gt;
 
 **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-useless"></a>useless |  Args with some tags: &lt;tag1&gt;, &lt;tag2&gt;   | String | optional | <code>"Find &lt;brackets&gt;"</code> |
 
 
 <a id="bracketuse"></a>
@@ -29,7 +32,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 &lt;brackets&gt;
 
 **FIELDS**
 
@@ -46,23 +49,54 @@ Information with <brackets>
 ## bracket_function
 
 <pre>
-bracket_function(<a href="#bracket_function-name">name</a>)
+bracket_function(<a href="#bracket_function-param">param</a>)
 </pre>
 
-Dummy docstring with <brackets>.
+Dummy docstring with &lt;brackets&gt;.
 
-This rule runs checks on <angle brackets>.
+This rule runs checks on &lt;angle brackets&gt;.
 
 
 **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, &lt;default&gt; by default.   |  <code>"&lt;default&gt;"</code> |
 
 **RETURNS**
 
-some <angled> brackets
+some &lt;angled&gt; brackets
+
+**DEPRECATED**
+
+deprecated for &lt;reasons&gt;
+
+
+<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 with &lt;brackets&gt;
+
+**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 |  <code>"&lt;default&gt;"</code>   |
 
 

test/testdata/angle_bracket_test/input.bzl

@@ -1,19 +1,23 @@
-"""Input file to test angle bracket bug (https://github.com/bazelbuild/skydoc/issues/186)"""
+"""Input file to test <angle bracket bugs>
 
-def bracket_function(name):
+See https://github.com/bazelbuild/skydoc/issues/186
+and https://github.com/bazelbuild/stardoc/issues/132"""
+
+def bracket_function(param = "<default>"):
     """Dummy docstring with <brackets>.
 
     This rule runs checks on <angle brackets>.
 
     Args:
-        name: an arg with **formatted** docstring.
+        param: an arg with **formatted** docstring, <default> by default.
 
     Returns:
         some <angled> brackets
 
+    Deprecated:
+        deprecated for <reasons>
     """
-    _ignore = name  # @unused
-    pass
+    return param
 
 # buildifier: disable=unsorted-dict-items
 bracketuse = provider(
@@ -39,3 +43,19 @@ my_anglebrac = rule(
         ),
     },
 )
+
+def _bracket_aspect_impl(ctx):
+    _ignore = [ctx]  # @unused
+    return []
+
+bracket_aspect = aspect(
+    implementation = _bracket_aspect_impl,
+    doc = "Aspect with <brackets>",
+    attr_aspects = ["deps"],
+    attrs = {
+        "brackets": attr.string(
+            doc = "Attribute with <brackets>",
+            default = "<default>",
+        ),
+    },
+)

test/testdata/apple_basic_test/golden.md

@@ -19,7 +19,7 @@ This rule does apple-related things.
 | :------------- | :------------- | :------------- | :------------- | :------------- |
 | <a id="apple_related_rule-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
 | <a id="apple_related_rule-first"></a>first |  -   | <a href="https://bazel.build/concepts/labels">Label</a> | required |  |
-| <a id="apple_related_rule-fourth"></a>fourth |  -   | Boolean | optional | False |
+| <a id="apple_related_rule-fourth"></a>fourth |  -   | Boolean | optional | <code>False</code> |
 | <a id="apple_related_rule-second"></a>second |  -   | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required |  |
 | <a id="apple_related_rule-third"></a>third |  -   | <a href="https://bazel.build/concepts/labels">Label</a> | required |  |