Do not HTML-escape and use Markdown inline code for defaults

docs/stardoc_rule.md

@@ -21,17 +21,17 @@ Generates documentation for exported starlark rule definitions in a target starl
 | <a id="stardoc-name"></a>name |  The name of the stardoc target.   |  none |
 | <a id="stardoc-input"></a>input |  The starlark file to generate documentation for (mandatory).   |  none |
 | <a id="stardoc-out"></a>out |  The file to which documentation will be output (mandatory).   |  none |
-| <a id="stardoc-deps"></a>deps |  A list of bzl_library dependencies which the input depends on.   |  <code>[]</code> |
-| <a id="stardoc-format"></a>format |  The format of the output file. Valid values: 'markdown' or 'proto'.   |  <code>"markdown"</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.   |  <code>[]</code> |
-| <a id="stardoc-semantic_flags"></a>semantic_flags |  A list of canonical flags to affect Starlark semantics for the Starlark interpreter 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".   |  <code>[]</code> |
-| <a id="stardoc-stardoc"></a>stardoc |  The location of the stardoc tool.   |  <code>Label("//stardoc:prebuilt_stardoc_binary")</code> |
-| <a id="stardoc-renderer"></a>renderer |  The location of the renderer tool.   |  <code>Label("//stardoc:renderer")</code> |
-| <a id="stardoc-aspect_template"></a>aspect_template |  The input file template for generating documentation of aspects   |  <code>Label("//stardoc:templates/markdown_tables/aspect.vm")</code> |
-| <a id="stardoc-func_template"></a>func_template |  The input file template for generating documentation of functions.   |  <code>Label("//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.   |  <code>Label("//stardoc:templates/markdown_tables/header.vm")</code> |
-| <a id="stardoc-provider_template"></a>provider_template |  The input file template for generating documentation of providers.   |  <code>Label("//stardoc:templates/markdown_tables/provider.vm")</code> |
-| <a id="stardoc-rule_template"></a>rule_template |  The input file template for generating documentation of rules.   |  <code>Label("//stardoc:templates/markdown_tables/rule.vm")</code> |
+| <a id="stardoc-deps"></a>deps |  A list of bzl_library dependencies which the input depends on.   |  `[]` |
+| <a id="stardoc-format"></a>format |  The format of the output file. Valid values: 'markdown' or 'proto'.   |  `"markdown"` |
+| <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.   |  `[]` |
+| <a id="stardoc-semantic_flags"></a>semantic_flags |  A list of canonical flags to affect Starlark semantics for the Starlark interpreter 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".   |  `[]` |
+| <a id="stardoc-stardoc"></a>stardoc |  The location of the stardoc tool.   |  `Label("//stardoc:prebuilt_stardoc_binary")` |
+| <a id="stardoc-renderer"></a>renderer |  The location of the renderer tool.   |  `Label("//stardoc:renderer")` |
+| <a id="stardoc-aspect_template"></a>aspect_template |  The input file template for generating documentation of aspects   |  `Label("//stardoc:templates/markdown_tables/aspect.vm")` |
+| <a id="stardoc-func_template"></a>func_template |  The input file template for generating documentation of functions.   |  `Label("//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.   |  `Label("//stardoc:templates/markdown_tables/header.vm")` |
+| <a id="stardoc-provider_template"></a>provider_template |  The input file template for generating documentation of providers.   |  `Label("//stardoc:templates/markdown_tables/provider.vm")` |
+| <a id="stardoc-rule_template"></a>rule_template |  The input file template for generating documentation of rules.   |  `Label("//stardoc:templates/markdown_tables/rule.vm")` |
 | <a id="stardoc-kwargs"></a>kwargs |  Further arguments to pass to stardoc.   |  none |
 
 

stardoc/templates/markdown_tables/aspect.vm

@@ -6,7 +6,7 @@
 ${util.aspectSummary($aspectName, $aspectInfo)}
 </pre>
 
-${util.htmlEscape($aspectInfo.getDocString())}
+$aspectInfo.getDocString()
 
 **ASPECT ATTRIBUTES**
 
@@ -27,6 +27,6 @@ ${util.htmlEscape($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)} | #if(!$attribute.defaultValue.isEmpty()) <code>${util.htmlEscape($attribute.defaultValue)}</code> #end  |
+| <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()) ${util.markdownCodeSpan($attribute.defaultValue)} #end |
 #end
 #end

stardoc/templates/markdown_tables/func.vm

@@ -6,7 +6,7 @@
 ${util.funcSummary($funcInfo)}
 </pre>
 
-${util.htmlEscape($funcInfo.docString)}
+${funcInfo.docString}
 
 #if (!$funcInfo.getParameterList().isEmpty())
 **PARAMETERS**
@@ -15,18 +15,18 @@ ${util.htmlEscape($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>${util.htmlEscape($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()) ${util.markdownCodeSpan($param.defaultValue)} #else none #end|
 #end
 #end
 #if (!$funcInfo.getReturn().docString.isEmpty())
 
 **RETURNS**
 
-${util.htmlEscape($funcInfo.getReturn().docString)}
+${funcInfo.getReturn().docString}
 #end
 #if (!$funcInfo.getDeprecated().docString.isEmpty())
 
 **DEPRECATED**
 
-${util.htmlEscape($funcInfo.getDeprecated().docString)}
+${funcInfo.getDeprecated().docString}
 #end

stardoc/templates/markdown_tables/header.vm

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

stardoc/templates/markdown_tables/provider.vm

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

stardoc/templates/markdown_tables/rule.vm

@@ -6,7 +6,7 @@
 ${util.ruleSummary($ruleName, $ruleInfo)}
 </pre>
 
-${util.htmlEscape($ruleInfo.docString)}
+${ruleInfo.docString}
 
 **ATTRIBUTES**
 
@@ -15,6 +15,6 @@ ${util.htmlEscape($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)} | #if(!$attribute.defaultValue.isEmpty())<code>${util.htmlEscape($attribute.defaultValue)}</code>#end |
+| <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()) ${util.markdownCodeSpan($attribute.defaultValue)} #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 | <code>False</code> |
+| <a id="android_related_rule-fourth"></a>fourth |  -   | Boolean | optional |  `False`  |
 | <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,27 +1,36 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
-Input file to test &lt;angle bracket bugs&gt;
+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>`).
 
-See https://github.com/bazelbuild/skydoc/issues/186
-and https://github.com/bazelbuild/stardoc/issues/132
 
 <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 &lt;brackets&gt;
+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 | <code>"Find &lt;brackets&gt;"</code> |
+| <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>
@@ -32,7 +41,7 @@ Rule with &lt;brackets&gt;
 bracketuse(<a href="#bracketuse-foo">foo</a>, <a href="#bracketuse-bar">bar</a>, <a href="#bracketuse-baz">baz</a>)
 </pre>
 
-Information with &lt;brackets&gt;
+Information with \<brackets>
 
 **FIELDS**
 
@@ -49,28 +58,36 @@ Information with &lt;brackets&gt;
 ## bracket_function
 
 <pre>
-bracket_function(<a href="#bracket_function-param">param</a>)
+bracket_function(<a href="#bracket_function-param">param</a>, <a href="#bracket_function-md_string">md_string</a>)
 </pre>
 
-Dummy docstring with &lt;brackets&gt;.
+Dummy docstring with \<brackets>.
+
+This rule runs checks on `<angle brackets>`.
 
-This rule runs checks on &lt;angle brackets&gt;.
+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-param"></a>param |  an arg with **formatted** docstring, &lt;default&gt; by default.   |  <code>"&lt;default&gt;"</code> |
+| <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 &lt;angled&gt; brackets
+some \<angled> brackets
 
 **DEPRECATED**
 
-deprecated for &lt;reasons&gt;
+deprecated for \<reasons> as well as `<reasons>`.
 
 
 <a id="bracket_aspect"></a>
@@ -81,7 +98,14 @@ deprecated for &lt;reasons&gt;
 bracket_aspect(<a href="#bracket_aspect-name">name</a>, <a href="#bracket_aspect-brackets">brackets</a>)
 </pre>
 
-Aspect with &lt;brackets&gt;
+Aspect.
+
+Sometimes, we want a code block like
+```starlark
+foo = "<brackets>"
+```
+which includes angle brackets.
+
 
 **ASPECT ATTRIBUTES**
 
@@ -96,7 +120,7 @@ Aspect with &lt;brackets&gt;
 
 | 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>   |
+| <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,27 +1,43 @@
-"""Input file to test <angle bracket bugs>
+"""Input file to test angle bracket bug (https://github.com/bazelbuild/skydoc/issues/186)
 
-See https://github.com/bazelbuild/skydoc/issues/186
-and https://github.com/bazelbuild/stardoc/issues/132"""
+See https://github.com/bazelbuild/skydoc/issues/186,
+https://github.com/bazelbuild/stardoc/issues/132,
+and https://github.com/bazelbuild/stardoc/issues/137.
 
-def bracket_function(param = "<default>"):
-    """Dummy docstring with <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>`).
+"""
 
-    This rule runs checks on <angle brackets>.
+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:
-        param: an arg with **formatted** docstring, <default> by default.
+        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>
+        deprecated for \\<reasons> as well as `<reasons>`.
     """
-    return param
+    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",
@@ -35,11 +51,15 @@ 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",
         ),
     },
 )
@@ -50,11 +70,18 @@ def _bracket_aspect_impl(ctx):
 
 bracket_aspect = aspect(
     implementation = _bracket_aspect_impl,
-    doc = "Aspect with <brackets>",
+    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>",
+            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 | <code>False</code> |
+| <a id="apple_related_rule-fourth"></a>fourth |  -   | Boolean | optional |  `False`  |
 | <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 |  |
 

test/testdata/aspect_test/golden.md

@@ -44,9 +44,9 @@ This is my aspect. It does stuff.
 
 | Name  | Description | Type | Mandatory | Default |
 | :------------- | :------------- | :------------- | :------------- | :------------- |
-| <a id="my_aspect-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |   |
-| <a id="my_aspect-first"></a>first |  -   | Boolean | required |   |
-| <a id="my_aspect-second"></a>second |  -   | String | required |   |
+| <a id="my_aspect-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
+| <a id="my_aspect-first"></a>first |  -   | Boolean | required |  |
+| <a id="my_aspect-second"></a>second |  -   | String | required |  |
 
 
 <a id="other_aspect"></a>
@@ -72,7 +72,7 @@ This is another aspect.
 
 | Name  | Description | Type | Mandatory | Default |
 | :------------- | :------------- | :------------- | :------------- | :------------- |
-| <a id="other_aspect-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |   |
-| <a id="other_aspect-third"></a>third |  -   | Integer | required |   |
+| <a id="other_aspect-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
+| <a id="other_aspect-third"></a>third |  -   | Integer | required |  |