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

33 files changed, 68 insertions, 0 deletions

diff --git a/docs/stardoc_rule.md b/docs/stardoc_rule.md
index ab2f6fa..8c55ef2 100644
--- 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
index 187680d..5556ad6 100644
--- 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
index 187680d..5556ad6 100644
--- 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
index 7612b40..465e581 100755
--- 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
index caa50d3..04e15d6 100755
--- 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
index c7852d0..15b38d8 100755
--- 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
index 4e4916d..e5fd51b 100755
--- 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
index 57b862e..b1a59da 100755
--- 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
index 97c793f..03fa626 100755
--- 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
index d80ffb6..d81de59 100755
--- 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
index c2170bf..4e63772 100755
--- 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
index 0606421..b5c2e20 100755
--- 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
index 1753264..82448fc 100755
--- 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
index d9d5a1b..4bd5e0e 100755
--- 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
index 054a37c..a05af55 100755
--- 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
index c791b1a..fbec191 100755
--- 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
index 74026de..5b8f4cd 100755
--- 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
index 54179fd..9dd924b 100755
--- 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
index 564502e..1e5ff6d 100755
--- 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
index 9f152f2..cf3169c 100755
--- 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
index a5f38cb..21d7fb8 100755
--- 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
index 7e2a289..46f9592 100644
--- 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
index 4257d10..e097ea1 100755
--- 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
index 71570af..5535326 100755
--- 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
index 0b17706..a320caa 100755
--- 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
index 4e065c3..4143e67 100755
--- 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
index 74f170a..d25414f 100755
--- 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
index 43b9747..eebc7c9 100755
--- 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
index 7987110..9acbf0f 100755
--- 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
index 054a37c..7d9f0d2 100755
--- 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
index 7baabc5..9492849 100755
--- 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
index 37f03be..1260be5 100755
--- 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
index 066ea9c..c5390d7 100755
--- 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