Update templates for macro returns and deprecations (#75)
Co-authored-by: Alexandre Rostovtsev <arostovtsev@google.com> (change section order)
diff --git a/stardoc/templates/html_tables/func.vm b/stardoc/templates/html_tables/func.vm
index e83bb94..3162beb 100644
--- a/stardoc/templates/html_tables/func.vm
+++ b/stardoc/templates/html_tables/func.vm
@@ -40,3 +40,16 @@
</tbody>
</table>
#end
+#if (!$funcInfo.getReturn().docString.isEmpty())
+
+#[[###]]# Returns
+
+${util.htmlEscape($funcInfo.getReturn().docString)}
+
+#end
+#if (!$funcInfo.getDeprecated().docString.isEmpty())
+
+#[[###]]# Deprecated
+
+${util.htmlEscape($funcInfo.getDeprecated().docString)}
+#end
diff --git a/stardoc/templates/markdown_tables/func.vm b/stardoc/templates/markdown_tables/func.vm
index e53e639..2ac9fe6 100644
--- a/stardoc/templates/markdown_tables/func.vm
+++ b/stardoc/templates/markdown_tables/func.vm
@@ -18,3 +18,15 @@
| <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|
#end
#end
+#if (!$funcInfo.getReturn().docString.isEmpty())
+
+**RETURNS**
+
+${funcInfo.getReturn().docString}
+#end
+#if (!$funcInfo.getDeprecated().docString.isEmpty())
+
+**DEPRECATED**
+
+${funcInfo.getDeprecated().docString}
+#end
diff --git a/test/testdata/angle_bracket_test/golden.md b/test/testdata/angle_bracket_test/golden.md
index 76d53dc..caa50d3 100755
--- a/test/testdata/angle_bracket_test/golden.md
+++ b/test/testdata/angle_bracket_test/golden.md
@@ -59,4 +59,8 @@
| :------------- | :------------- | :------------- |
| <a id="bracket_function-name"></a>name | an arg with **formatted** docstring. | none |
+**RETURNS**
+
+some <angled> brackets
+
diff --git a/test/testdata/function_basic_test/golden.md b/test/testdata/function_basic_test/golden.md
index ceb7718..d9d5a1b 100755
--- a/test/testdata/function_basic_test/golden.md
+++ b/test/testdata/function_basic_test/golden.md
@@ -30,6 +30,44 @@
| <a id="check_sources-struct_param"></a>struct_param | <p align="center"> - </p> | <code>struct(foo = "bar")</code> |
+<a id="#deprecated_do_not_use"></a>
+
+## deprecated_do_not_use
+
+<pre>
+deprecated_do_not_use()
+</pre>
+
+This function is deprecated.
+
+
+**DEPRECATED**
+
+Use literally anything but this function.
+
+
+<a id="#returns_a_thing"></a>
+
+## returns_a_thing
+
+<pre>
+returns_a_thing(<a href="#returns_a_thing-name">name</a>)
+</pre>
+
+Returns a suffixed name.
+
+**PARAMETERS**
+
+
+| Name | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="returns_a_thing-name"></a>name | A unique name for this rule. | none |
+
+**RETURNS**
+
+A suffixed version of the name.
+
+
<a id="#undocumented_function"></a>
## undocumented_function
diff --git a/test/testdata/function_basic_test/input.bzl b/test/testdata/function_basic_test/input.bzl
index 721e1d3..cff5b48 100644
--- a/test/testdata/function_basic_test/input.bzl
+++ b/test/testdata/function_basic_test/input.bzl
@@ -34,5 +34,24 @@
]
x = ("Hah. All that documentation but nothing really to see here")
+def returns_a_thing(name):
+ """Returns a suffixed name.
+
+ Args:
+ name: A unique name for this rule.
+
+ Returns:
+ A suffixed version of the name.
+ """
+ pass
+
+def deprecated_do_not_use():
+ """This function is deprecated.
+
+ Deprecated:
+ Use literally anything but this function.
+ """
+ pass
+
def undocumented_function(a, b, c):
pass
diff --git a/test/testdata/local_repository_test/golden.md b/test/testdata/local_repository_test/golden.md
index 7f6d532..54179fd 100755
--- a/test/testdata/local_repository_test/golden.md
+++ b/test/testdata/local_repository_test/golden.md
@@ -17,4 +17,8 @@
| :------------- | :------------- | :------------- |
| <a id="min-integers"></a>integers | A list of integers. Must not be empty. | none |
+**RETURNS**
+
+The minimum integer in the given list.
+
diff --git a/test/testdata/macro_kwargs_test/golden.md b/test/testdata/macro_kwargs_test/golden.md
index 7f0bae9..564502e 100755
--- a/test/testdata/macro_kwargs_test/golden.md
+++ b/test/testdata/macro_kwargs_test/golden.md
@@ -18,6 +18,10 @@
| <a id="macro_with_args-name"></a>name | The name of the test rule. | none |
| <a id="macro_with_args-args"></a>args | Other arguments to include | none |
+**RETURNS**
+
+An empty list.
+
<a id="#macro_with_both"></a>
@@ -42,6 +46,10 @@
| <a id="macro_with_both-args"></a>args | Other arguments to include | none |
| <a id="macro_with_both-kwargs"></a>kwargs | Other attributes to include | none |
+**RETURNS**
+
+An empty list.
+
<a id="#macro_with_kwargs"></a>
@@ -70,4 +78,8 @@
| <a id="macro_with_kwargs-deps"></a>deps | List of my macro's dependencies | <code>[]</code> |
| <a id="macro_with_kwargs-kwargs"></a>kwargs | Other attributes to include | none |
+**RETURNS**
+
+An empty list.
+
diff --git a/test/testdata/multi_level_namespace_test/golden.md b/test/testdata/multi_level_namespace_test/golden.md
index de233ac..a5f38cb 100755
--- a/test/testdata/multi_level_namespace_test/golden.md
+++ b/test/testdata/multi_level_namespace_test/golden.md
@@ -17,6 +17,10 @@
| :------------- | :------------- | :------------- |
| <a id="my_namespace.min-integers"></a>integers | A list of integers. Must not be empty. | none |
+**RETURNS**
+
+The minimum integer in the given list.
+
<a id="#my_namespace.math.min"></a>
@@ -35,6 +39,10 @@
| :------------- | :------------- | :------------- |
| <a id="my_namespace.math.min-integers"></a>integers | A list of integers. Must not be empty. | none |
+**RETURNS**
+
+The minimum integer in the given list.
+
<a id="#my_namespace.foo.bar.baz"></a>
@@ -65,6 +73,10 @@
| :------------- | :------------- | :------------- |
| <a id="my_namespace.one.two.min-integers"></a>integers | A list of integers. Must not be empty. | none |
+**RETURNS**
+
+The minimum integer in the given list.
+
<a id="#my_namespace.one.three.does_nothing"></a>
diff --git a/test/testdata/namespace_test/golden.md b/test/testdata/namespace_test/golden.md
index b9584f7..0b17706 100755
--- a/test/testdata/namespace_test/golden.md
+++ b/test/testdata/namespace_test/golden.md
@@ -36,6 +36,10 @@
| :------------- | :------------- | :------------- |
| <a id="my_namespace.min-integers"></a>integers | A list of integers. Must not be empty. | none |
+**RETURNS**
+
+The minimum integer in the given list.
+
<a id="#my_namespace.join_strings"></a>
@@ -55,4 +59,8 @@
| <a id="my_namespace.join_strings-strings"></a>strings | A list of strings to join. | none |
| <a id="my_namespace.join_strings-delimiter"></a>delimiter | The delimiter to use | <code>", "</code> |
+**RETURNS**
+
+The joined string.
+
