Include the module's docstring in the header (#100)

bazelbuild · Oct 4, 2021 · 336d405 · 336d405
1 parent af6e88d
commit 336d405
Show file tree

Hide file tree

Showing 33 changed files with 68 additions and 0 deletions.
diff --git a/docs/stardoc_rule.md b/docs/stardoc_rule.md
@@ -1,5 +1,7 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
+Starlark rule for stardoc: a documentation generator tool written in Java.
+
 <a id="#stardoc"></a>
 
 ## stardoc

diff --git a/stardoc/templates/html_tables/header.vm b/stardoc/templates/html_tables/header.vm
@@ -1 +1,3 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
+
+${moduleDocstring}
diff --git a/stardoc/templates/markdown_tables/header.vm b/stardoc/templates/markdown_tables/header.vm
@@ -1 +1,3 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
+
+${moduleDocstring}
diff --git a/test/testdata/android_basic_test/golden.md b/test/testdata/android_basic_test/golden.md
@@ -1,5 +1,7 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
+
+
 <a id="#android_related_rule"></a>
 
 ## android_related_rule

diff --git a/test/testdata/angle_bracket_test/golden.md b/test/testdata/angle_bracket_test/golden.md
@@ -1,5 +1,7 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
+Input file to test angle bracket bug (https://github.com/bazelbuild/skydoc/issues/186)
+
 <a id="#my_anglebrac"></a>
 
 ## my_anglebrac

diff --git a/test/testdata/apple_basic_test/golden.md b/test/testdata/apple_basic_test/golden.md
@@ -1,5 +1,7 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
+
+
 <a id="#apple_related_rule"></a>
 
 ## apple_related_rule

diff --git a/test/testdata/aspect_test/golden.md b/test/testdata/aspect_test/golden.md
@@ -1,5 +1,7 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
+The input file for the aspect test
+
 <a id="#my_aspect_impl"></a>
 
 ## my_aspect_impl

diff --git a/test/testdata/attribute_defaults_test/golden.md b/test/testdata/attribute_defaults_test/golden.md
@@ -1,5 +1,7 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
+A golden test to verify attribute default values.
+
 <a id="#my_rule"></a>
 
 ## my_rule

diff --git a/test/testdata/attribute_types_test/golden.md b/test/testdata/attribute_types_test/golden.md
@@ -1,5 +1,7 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
+
+
 <a id="#my_rule"></a>
 
 ## my_rule

diff --git a/test/testdata/cc_api_test/golden.md b/test/testdata/cc_api_test/golden.md
@@ -1,5 +1,7 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
+Input file for C++ api test 
+
 <a id="#cpp_related_rule"></a>
 
 ## cpp_related_rule

diff --git a/test/testdata/config_apis_test/golden.md b/test/testdata/config_apis_test/golden.md
@@ -1,5 +1,7 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
+
+
 <a id="#int_setting"></a>
 
 ## int_setting

diff --git a/test/testdata/cpp_basic_test/golden.md b/test/testdata/cpp_basic_test/golden.md
@@ -1,5 +1,7 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
+
+
 <a id="#cpp_related_rule"></a>
 
 ## cpp_related_rule

diff --git a/test/testdata/filter_rules_test/golden.md b/test/testdata/filter_rules_test/golden.md
@@ -1,5 +1,7 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
+
+
 <a id="#my_rule"></a>
 
 ## my_rule

diff --git a/test/testdata/function_basic_test/golden.md b/test/testdata/function_basic_test/golden.md
@@ -1,5 +1,7 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
+A test that verifies basic user function documentation.
+
 <a id="#check_sources"></a>
 
 ## check_sources

diff --git a/test/testdata/generated_bzl_test/golden.md b/test/testdata/generated_bzl_test/golden.md
@@ -1,5 +1,7 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
+A direct dependency file of the input file.
+
 <a id="#my_rule"></a>
 
 ## my_rule

diff --git a/test/testdata/html_tables_template_test/golden.md b/test/testdata/html_tables_template_test/golden.md
@@ -1,5 +1,7 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
+Input file for markdown template test
+
 <a id="#example_rule"></a>
 
 ## example_rule

diff --git a/test/testdata/java_basic_test/golden.md b/test/testdata/java_basic_test/golden.md
@@ -1,5 +1,7 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
+
+
 <a id="#java_related_rule"></a>
 
 ## java_related_rule

diff --git a/test/testdata/local_repository_test/golden.md b/test/testdata/local_repository_test/golden.md
@@ -1,5 +1,7 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
+A test that verifies documenting functions in an input file under a local_repository.
+
 <a id="#min"></a>
 
 ## min

diff --git a/test/testdata/macro_kwargs_test/golden.md b/test/testdata/macro_kwargs_test/golden.md
@@ -1,5 +1,7 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
+Tests for functions which use *args or **kwargs
+
 <a id="#macro_with_args"></a>
 
 ## macro_with_args

diff --git a/test/testdata/misc_apis_test/golden.md b/test/testdata/misc_apis_test/golden.md
@@ -1,5 +1,7 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
+
+
 <a id="#my_rule"></a>
 
 ## my_rule

diff --git a/test/testdata/multi_level_namespace_test/golden.md b/test/testdata/multi_level_namespace_test/golden.md
@@ -1,5 +1,7 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
+A test that verifies documenting a multi-leveled namespace of functions.
+
 <a id="#my_namespace.min"></a>
 
 ## my_namespace.min

diff --git a/test/testdata/multi_level_namespace_test_with_whitelist/golden.md b/test/testdata/multi_level_namespace_test_with_whitelist/golden.md
@@ -1,5 +1,9 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
+A test that verifies documenting a multi-leveled namespace of functions with whitelist symbols.
+The whitelist symbols should cause everything in my_namespace to to be documented, but only a
+specific symbol in other_namespace to be documented.
+
 <a id="#my_namespace.min"></a>
 
 ## my_namespace.min

diff --git a/test/testdata/multiple_files_test/golden.md b/test/testdata/multiple_files_test/golden.md
@@ -1,5 +1,7 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
+A direct dependency file of the input file.
+
 <a id="#my_rule"></a>
 
 ## my_rule

diff --git a/test/testdata/multiple_rules_test/golden.md b/test/testdata/multiple_rules_test/golden.md
@@ -1,5 +1,7 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
+
+
 <a id="#my_rule"></a>
 
 ## my_rule

diff --git a/test/testdata/namespace_test/golden.md b/test/testdata/namespace_test/golden.md
@@ -1,5 +1,7 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
+A test that verifies documenting a namespace of functions.
+
 <a id="#my_namespace.assert_non_empty"></a>
 
 ## my_namespace.assert_non_empty

diff --git a/test/testdata/provider_basic_test/golden.md b/test/testdata/provider_basic_test/golden.md
@@ -1,5 +1,7 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
+
+
 <a id="#MyFooInfo"></a>
 
 ## MyFooInfo

diff --git a/test/testdata/providers_for_attributes_test/golden.md b/test/testdata/providers_for_attributes_test/golden.md
@@ -1,5 +1,7 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
+The input file for the providers for attributes test
+
 <a id="#my_rule"></a>
 
 ## my_rule

diff --git a/test/testdata/py_rule_test/golden.md b/test/testdata/py_rule_test/golden.md
@@ -1,5 +1,7 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
+The input file for the python rule test
+
 <a id="#py_related_rule"></a>
 
 ## py_related_rule

diff --git a/test/testdata/repo_rules_test/golden.md b/test/testdata/repo_rules_test/golden.md
@@ -1,5 +1,7 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
+
+
 <a id="#my_repo"></a>
 
 ## my_repo

diff --git a/test/testdata/same_level_file_test/golden.md b/test/testdata/same_level_file_test/golden.md
@@ -1,5 +1,7 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
+
+
 <a id="#my_rule"></a>
 
 ## my_rule

diff --git a/test/testdata/simple_test/golden.md b/test/testdata/simple_test/golden.md
@@ -1,5 +1,7 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
+
+
 <a id="#my_rule"></a>
 
 ## my_rule

diff --git a/test/testdata/struct_default_value_test/golden.md b/test/testdata/struct_default_value_test/golden.md
@@ -1,5 +1,7 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
+The input file for struct default values test
+
 <a id="#check_struct_default_values"></a>
 
 ## check_struct_default_values

diff --git a/test/testdata/unknown_name_test/golden.md b/test/testdata/unknown_name_test/golden.md
@@ -1,5 +1,7 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
+
+
 <a id="#my_rule_impl"></a>
 
 ## my_rule_impl