diff options
Diffstat (limited to 'test')
72 files changed, 306 insertions, 1463 deletions
@@ -1,15 +1,18 @@ -load(":stardoc_test.bzl", "self_gen_test", "stardoc_test") -load("@bazel_skylib//rules:diff_test.bzl", "diff_test") - -package(default_applicable_licenses = ["//:license"]) +load(":stardoc_test.bzl", "stardoc_test") licenses(["notice"]) # Apache 2.0 -self_gen_test( +sh_test( name = "stardoc_self_gen_test", - golden_file = "//stardoc:stardoc_doc.md", - require_starlark_doc_extract = True, - stardoc_doc = "//:stardoc_rule_doc", + srcs = ["diff_test_runner.sh"], + args = [ + "$(location //stardoc:stardoc_doc.md)", + "$(location //:stardoc_rule_doc)", + ], + data = [ + "//:stardoc_rule_doc", + "//stardoc:stardoc_doc.md", + ], ) exports_files(["testdata/fakedeps/dep.bzl"]) @@ -29,15 +32,13 @@ stardoc_test( name = "angle_bracket_test", golden_file = "testdata/angle_bracket_test/golden.md", input_file = "testdata/angle_bracket_test/input.bzl", - legacy_golden_file = "testdata/angle_bracket_test/legacy_golden.md", ) stardoc_test( name = "proto_format_test", format = "proto", - golden_file = "testdata/proto_format_test/golden.binaryproto", + golden_file = "testdata/proto_format_test/golden.raw", input_file = "testdata/proto_format_test/input.bzl", - legacy_golden_file = "testdata/proto_format_test/legacy_golden.binaryproto", ) stardoc_test( @@ -57,14 +58,6 @@ stardoc_test( name = "repo_rules_test", golden_file = "testdata/repo_rules_test/golden.md", input_file = "testdata/repo_rules_test/input.bzl", - legacy_golden_file = "testdata/repo_rules_test/legacy_golden.md", -) - -stardoc_test( - name = "module_extension_test", - golden_file = "testdata/module_extension_test/golden.md", - input_file = "testdata/module_extension_test/input.bzl", - test_legacy_extractor = False, ) stardoc_test( @@ -134,14 +127,12 @@ stardoc_test( name = "misc_apis_test", golden_file = "testdata/misc_apis_test/golden.md", input_file = "testdata/misc_apis_test/input.bzl", - legacy_golden_file = "testdata/misc_apis_test/legacy_golden.md", ) stardoc_test( name = "attribute_types_test", golden_file = "testdata/attribute_types_test/golden.md", input_file = "testdata/attribute_types_test/input.bzl", - legacy_golden_file = "testdata/attribute_types_test/legacy_golden.md", symbol_names = ["my_rule"], ) @@ -151,7 +142,7 @@ stardoc_test( input_file = "testdata/filter_rules_test/input.bzl", symbol_names = [ "my_rule", - "allowlisted_dep_rule", + "whitelisted_dep_rule", ], deps = [ "testdata/filter_rules_test/dep.bzl", @@ -162,7 +153,6 @@ stardoc_test( name = "provider_basic_test", golden_file = "testdata/provider_basic_test/golden.md", input_file = "testdata/provider_basic_test/input.bzl", - legacy_golden_file = "testdata/provider_basic_test/legacy_golden.md", ) stardoc_test( @@ -172,20 +162,13 @@ stardoc_test( ) stardoc_test( - name = "function_wrap_multiple_lines_test", - golden_file = "testdata/function_wrap_multiple_lines_test/golden.md", - input_file = "testdata/function_wrap_multiple_lines_test/input.bzl", - legacy_golden_file = "testdata/function_wrap_multiple_lines_test/legacy_golden.md", -) - -stardoc_test( name = "namespace_test", golden_file = "testdata/namespace_test/golden.md", input_file = "testdata/namespace_test/input.bzl", ) stardoc_test( - name = "namespace_test_with_allowlist", + name = "namespace_test_with_whitelist", golden_file = "testdata/namespace_test/golden.md", input_file = "testdata/namespace_test/input.bzl", symbol_names = [ @@ -200,9 +183,9 @@ stardoc_test( ) stardoc_test( - name = "multi_level_namespace_test_with_allowlist", - golden_file = "testdata/multi_level_namespace_test_with_allowlist/golden.md", - input_file = "testdata/multi_level_namespace_test_with_allowlist/input.bzl", + name = "multi_level_namespace_test_with_whitelist", + golden_file = "testdata/multi_level_namespace_test_with_whitelist/golden.md", + input_file = "testdata/multi_level_namespace_test_with_whitelist/input.bzl", symbol_names = [ "my_namespace", "other_namespace.foo.nothing", @@ -216,12 +199,6 @@ stardoc_test( ) stardoc_test( - name = "pure_markdown_template_test", - golden_file = "testdata/pure_markdown_template_test/golden.md", - input_file = "testdata/pure_markdown_template_test/input.bzl", -) - -stardoc_test( name = "py_rule_test", golden_file = "testdata/py_rule_test/golden.md", input_file = "testdata/py_rule_test/input.bzl", @@ -238,7 +215,6 @@ stardoc_test( name = "aspect_test", golden_file = "testdata/aspect_test/golden.md", input_file = "testdata/aspect_test/input.bzl", - legacy_golden_file = "testdata/aspect_test/legacy_golden.md", ) stardoc_test( @@ -261,7 +237,6 @@ stardoc_test( name = "attribute_defaults_test", golden_file = "testdata/attribute_defaults_test/golden.md", input_file = "testdata/attribute_defaults_test/input.bzl", - legacy_golden_file = "testdata/attribute_defaults_test/legacy_golden.md", ) stardoc_test( @@ -270,6 +245,22 @@ stardoc_test( input_file = "testdata/config_apis_test/input.bzl", ) +genrule( + name = "generate_bzl_test_dep", + srcs = ["testdata/generated_bzl_test/dep.bzl.tpl"], + outs = ["testdata/generated_bzl_test/dep.bzl"], + cmd = "cp $< $@", +) + +stardoc_test( + name = "generated_bzl_test", + golden_file = "testdata/generated_bzl_test/golden.md", + input_file = "testdata/generated_bzl_test/input.bzl", + deps = [ + "testdata/generated_bzl_test/dep.bzl", + ], +) + sh_test( name = "local_repository_test_e2e_test", srcs = ["diff_test_runner.sh"], @@ -282,51 +273,3 @@ sh_test( "@local_repository_test//:output.md", ], ) - -# Consistency tests for WORKSPACE-related .bzl files vs. MODULE.bazel - -genrule( - name = "stardoc_maven_artifacts_in_deps_bzl", - srcs = ["//:deps.bzl"], - outs = ["stardoc_maven_artifacts_in_deps_bzl.txt"], - # Remove all lines except those from 'STARDOC_MAVEN_ARTIFACTS = [' to next ']' - cmd = "sed -e '/STARDOC_MAVEN_ARTIFACTS = \\[/,/\\]/!d' $< >$@", -) - -genrule( - name = "stardoc_maven_artifacts_in_module_bazel", - srcs = ["//:MODULE.bazel"], - outs = ["stardoc_maven_artifacts_in_module_bazel.txt"], - # Remove all lines except those from 'STARDOC_MAVEN_ARTIFACTS = [' to next ']' - cmd = "sed -e '/STARDOC_MAVEN_ARTIFACTS = \\[/,/\\]/!d' $< >$@", -) - -diff_test( - name = "stardoc_maven_artifacts_consistency_test", - failure_message = "STARDOC_MAVEN_ARTIFACTS in deps.bzl and MODULE.bazel are inconsistent", - file1 = "stardoc_maven_artifacts_in_deps_bzl", - file2 = "stardoc_maven_artifacts_in_module_bazel", -) - -genrule( - name = "stardoc_version_in_version_bzl", - srcs = ["//:version.bzl"], - outs = ["stardoc_version_in_version_bzl.txt"], - # Find first line starting containing 'version = ' and extract the string value - cmd = "grep -m 1 'version = ' $< | sed -e 's/.*version = \\(\".*\"\\).*/\\1/' >$@", -) - -genrule( - name = "stardoc_version_in_module_bazel", - srcs = ["//:MODULE.bazel"], - outs = ["stardoc_version_in_module_bazel.txt"], - # Find first line starting containing 'version = ' and extract the string value - cmd = "grep -m 1 'version = ' $< | sed -e 's/.*version = \\(\".*\"\\).*/\\1/' >$@", -) - -diff_test( - name = "stardoc_version_consistency_test", - failure_message = "version in version.bzl and MODULE.bazel is inconsistent", - file1 = "stardoc_version_in_version_bzl", - file2 = "stardoc_version_in_module_bazel", -) diff --git a/test/bzlmod/.bazelrc b/test/bzlmod/.bazelrc deleted file mode 100644 index 3ce91d2..0000000 --- a/test/bzlmod/.bazelrc +++ /dev/null @@ -1 +0,0 @@ -common --enable_bzlmod diff --git a/test/bzlmod/BUILD b/test/bzlmod/BUILD deleted file mode 100644 index 91fd15a..0000000 --- a/test/bzlmod/BUILD +++ /dev/null @@ -1,23 +0,0 @@ -load("@my_skylib//rules:diff_test.bzl", "diff_test") -load("@stardoc//stardoc:stardoc.bzl", "stardoc") -load(":def.bzl", "write_host_constraints") - -write_host_constraints( - name = "host_constraints", -) - -stardoc( - name = "docs", - out = "docs.md", - input = "def.bzl", - deps = [ - "@local_config_platform//:constraints.bzl", - "@my_skylib//rules:write_file", - ], -) - -diff_test( - name = "docs_test", - file1 = "docs.md", - file2 = "docs.md.golden", -) diff --git a/test/bzlmod/MODULE.bazel b/test/bzlmod/MODULE.bazel deleted file mode 100644 index 2c6b694..0000000 --- a/test/bzlmod/MODULE.bazel +++ /dev/null @@ -1,11 +0,0 @@ -bazel_dep(name = "stardoc", version = "") -local_path_override( - module_name = "stardoc", - path = "../..", -) - -bazel_dep( - name = "bazel_skylib", - version = "1.4.0", - repo_name = "my_skylib", -) diff --git a/test/bzlmod/WORKSPACE b/test/bzlmod/WORKSPACE deleted file mode 100644 index e69de29..0000000 --- a/test/bzlmod/WORKSPACE +++ /dev/null diff --git a/test/bzlmod/WORKSPACE.bzlmod b/test/bzlmod/WORKSPACE.bzlmod deleted file mode 100644 index e69de29..0000000 --- a/test/bzlmod/WORKSPACE.bzlmod +++ /dev/null diff --git a/test/bzlmod/def.bzl b/test/bzlmod/def.bzl deleted file mode 100644 index 8970cca..0000000 --- a/test/bzlmod/def.bzl +++ /dev/null @@ -1,31 +0,0 @@ -# Copyright 2023 The Bazel Authors. All rights reserved. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -"""A simple macro used to test stardoc.""" - -load("@my_skylib//rules:write_file.bzl", "write_file") -load("@local_config_platform//:constraints.bzl", "HOST_CONSTRAINTS") - -def write_host_constraints(name): - """Emits the constraints of the host platform to a file. - - Args: - name: The name of the target. The output file will be named - `<name>.txt`. - """ - write_file( - name = name, - content = HOST_CONSTRAINTS, - out = name + ".txt", - ) diff --git a/test/bzlmod/docs.md.golden b/test/bzlmod/docs.md.golden deleted file mode 100644 index 3b671cc..0000000 --- a/test/bzlmod/docs.md.golden +++ /dev/null @@ -1,22 +0,0 @@ -<!-- Generated with Stardoc: http://skydoc.bazel.build --> - -A simple macro used to test stardoc. - -<a id="write_host_constraints"></a> - -## write_host_constraints - -<pre> -write_host_constraints(<a href="#write_host_constraints-name">name</a>) -</pre> - -Emits the constraints of the host platform to a file. - -**PARAMETERS** - - -| Name | Description | Default Value | -| :------------- | :------------- | :------------- | -| <a id="write_host_constraints-name"></a>name | The name of the target. The output file will be named `<name>.txt`. | none | - - diff --git a/test/stardoc_test.bzl b/test/stardoc_test.bzl index d782643..8a18b52 100644 --- a/test/stardoc_test.bzl +++ b/test/stardoc_test.bzl @@ -21,27 +21,21 @@ def stardoc_test( name, input_file, golden_file, - legacy_golden_file = None, - test_legacy_extractor = True, deps = [], test = "default", **kwargs): """Convenience macro for stardoc e2e test suites. - Each invocation creates multiple targets: + Each invocation creates four targets: 1. A sh_test target which verifies that stardoc-built-from-source, when run on an input file, - creates output matching the contents of a golden file, named "{name}_e2e_legacy_test". - 2. A `stardoc` target which will generate a new golden file given an input file with the - legacy extractor built from Bazel source. This target should be used to regenerate the - legacy golden file when updating stardoc, named "regenerate_{name}_legacy_golden". + creates output matching the contents of a golden file, named "{name}_e2e_test". + 2. A `stardoc` target which will generate a new golden file given an input file + with stardoc-built-from-source. This target should be used to regenerate + the golden file when updating stardoc, named "regenerate_{name}_golden". 3 & 4. Targets identical to (1) and (2) except they use the prebuilt-stardoc jar, and - are named "{name}_e2e_jar_legacy_test" and "regenerate_with_jar_{name}_legacy_golden". - 5 & 6. Only if the host Bazel supports the `native.starlark_doc_extract` rule: Targets - identical to (1) and (2) except they use starlark_doc_extract, and are named "{name}_e2e_test" - and "regenerate_{name}_golden". The latter target should be used to regenerate the golden - file when updating Stardoc. - 7. A bzl_library target for convenient wrapping of input bzl files, named "{name}_lib". + are named "{name}_e2e_jar_test" and "regenerate_with_jar_{name}_golden". + 5. A bzl_library target for convenient wrapping of input bzl files, named "{name}_lib". Args: name: A unique name to qualify the created targets. @@ -49,60 +43,38 @@ def stardoc_test( in this test. golden_file: The label string of the golden file containing the documentation when stardoc is run on the input file. - legacy_golden_file: The label string of the golden file when using the legacy documentation - extractor. If `legacy_golden_file` is not set, `golden_file` will be used for both extractors. - test_legacy_extractor: Whether to create legacy extractor test targets. deps: A list of label strings of starlark file dependencies of the input_file. test: The type of test (default or html_tables). **kwargs: A dictionary of input template names mapped to template file path for which documentation is generated. """ - if legacy_golden_file == None: - legacy_golden_file = golden_file - bzl_library( name = "%s_lib" % name, srcs = [input_file], deps = deps, ) - - if test_legacy_extractor: - _create_test_targets( - test_name = "%s_e2e_legacy_test" % name, - genrule_name = "regenerate_%s_legacy_golden" % name, - lib_name = "%s_lib" % name, - input_file = input_file, - golden_file = legacy_golden_file, - stardoc_bin = "@io_bazel//src/main/java/com/google/devtools/build/skydoc:skydoc_deploy.jar", - test = test, - use_starlark_doc_extract = False, - **kwargs - ) - - _create_test_targets( - test_name = "%s_e2e_jar_legacy_test" % name, - genrule_name = "regenerate_with_jar_%s_legacy_golden" % name, - lib_name = "%s_lib" % name, - input_file = input_file, - golden_file = legacy_golden_file, - stardoc_bin = "@io_bazel//src/main/java/com/google/devtools/build/skydoc:skydoc_deploy.jar", - test = test, - use_starlark_doc_extract = False, - **kwargs - ) - - if hasattr(native, "starlark_doc_extract"): - _create_test_targets( - test_name = "%s_e2e_test" % name, - genrule_name = "regenerate_%s_golden" % name, - lib_name = "%s_lib" % name, - input_file = input_file, - golden_file = golden_file, - stardoc_bin = None, - test = test, - use_starlark_doc_extract = True, - **kwargs - ) + _create_test_targets( + test_name = "%s_e2e_test" % name, + genrule_name = "regenerate_%s_golden" % name, + lib_name = "%s_lib" % name, + input_file = input_file, + golden_file = golden_file, + stardoc_bin = "@io_bazel//src/main/java/com/google/devtools/build/skydoc", + renderer_bin = "@io_bazel//src/main/java/com/google/devtools/build/skydoc/renderer", + test = test, + **kwargs + ) + _create_test_targets( + test_name = "%s_e2e_jar_test" % name, + genrule_name = "regenerate_with_jar_%s_golden" % name, + lib_name = "%s_lib" % name, + input_file = input_file, + golden_file = golden_file, + stardoc_bin = "@io_bazel//src/main/java/com/google/devtools/build/skydoc", + renderer_bin = "@io_bazel//src/main/java/com/google/devtools/build/skydoc/renderer", + test = test, + **kwargs + ) def _create_test_targets( test_name, @@ -111,6 +83,7 @@ def _create_test_targets( input_file, golden_file, stardoc_bin, + renderer_bin, test, **kwargs): actual_generated_doc = "%s.out" % genrule_name @@ -134,6 +107,7 @@ def _create_test_targets( out = actual_generated_doc, input = input_file, deps = [lib_name], + renderer = renderer_bin, stardoc = stardoc_bin, **kwargs ) @@ -143,42 +117,9 @@ def _create_test_targets( out = actual_generated_doc, input = input_file, deps = [lib_name], + renderer = renderer_bin, stardoc = stardoc_bin, **kwargs ) else: fail("parameter 'test' must either be 'default' or 'html_tables', but was " + test) - -def self_gen_test( - name, - stardoc_doc, - golden_file, - require_starlark_doc_extract, - **kwargs): - """ - A wrapper around `diff_test_runner.sh` for testing Stardoc's own generated documentation. - - Args: - name: A unique name for the test target. - stardoc_doc: The Stardoc output being tested. - golden_file: Expected Stardoc output. - require_starlark_doc_extract: If true, and the native `starlark_doc_extract` rule is not available, - then no test target will not be created. - **kwargs: Additional arguments for the test. - """ - if require_starlark_doc_extract and not hasattr(native, "starlark_doc_extract"): - return - - native.sh_test( - name = name, - srcs = ["diff_test_runner.sh"], - args = [ - "$(location %s)" % golden_file, - "$(location %s)" % stardoc_doc, - ], - data = [ - golden_file, - stardoc_doc, - ], - **kwargs - ) diff --git a/test/testdata/android_basic_test/golden.md b/test/testdata/android_basic_test/golden.md index b22186d..0962201 100644..100755 --- a/test/testdata/android_basic_test/golden.md +++ b/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 | | diff --git a/test/testdata/android_basic_test/input.bzl b/test/testdata/android_basic_test/input.bzl index 0462c98..970b674 100644 --- a/test/testdata/android_basic_test/input.bzl +++ b/test/testdata/android_basic_test/input.bzl @@ -2,7 +2,14 @@ # buildifier: disable=function-docstring # buildifier: disable=unused-variable def exercise_the_api(): - _ignore = android_common.create_device_broker_info("") + _var1 = android_common.create_device_broker_info("") + _var2 = ApkInfo + _var3 = AndroidInstrumentationInfo + _var4 = AndroidDeviceBrokerInfo + _var5 = AndroidResourcesInfo + _var6 = AndroidNativeLibsInfo + _var7 = AndroidSdkInfo + _var8 = android_data exercise_the_api() diff --git a/test/testdata/angle_bracket_test/golden.md b/test/testdata/angle_bracket_test/golden.md index 06496b2..1c31dd2 100644..100755 --- a/test/testdata/angle_bracket_test/golden.md +++ b/test/testdata/angle_bracket_test/golden.md @@ -1,26 +1,19 @@ <!-- 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 <angle bracket bugs> -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 (`<` becomes <). -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-also_useless">also_useless</a>, <a href="#my_anglebrac-useless">useless</a>) +my_anglebrac(<a href="#my_anglebrac-name">name</a>, <a href="#my_anglebrac-useless">useless</a>) </pre> -Rule with \<brackets> +Rule with <brackets> **ATTRIBUTES** @@ -28,8 +21,7 @@ Rule with \<brackets> | 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-also_useless"></a>also_useless | Args with some formatted tags: `<tag>` and <pre><code class="language-xml"><tag2>x</tag2></code></pre> | String | optional | `"1<<5"` | -| <a id="my_anglebrac-useless"></a>useless | Args with some tags: \<tag1>, \<tag2> | String | optional | `"Find \\<brackets>"` | +| <a id="my_anglebrac-useless"></a>useless | Args with some tags: <tag1>, <tag2> | String | optional | <code>"Find <brackets>"</code> | <a id="bracketuse"></a> @@ -40,14 +32,14 @@ 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 <brackets> **FIELDS** | Name | Description | | :------------- | :------------- | -| <a id="bracketuse-foo"></a>foo | A string representing \<foo> | +| <a id="bracketuse-foo"></a>foo | A string representing <foo> | | <a id="bracketuse-bar"></a>bar | A string representing bar | | <a id="bracketuse-baz"></a>baz | A string representing baz | @@ -57,19 +49,12 @@ Information with \<brackets> ## bracket_function <pre> -bracket_function(<a href="#bracket_function-param">param</a>, <a href="#bracket_function-md_string">md_string</a>) +bracket_function(<a href="#bracket_function-param">param</a>) </pre> -Dummy docstring with \<brackets>. - -This rule runs checks on `<angle brackets>`. +Dummy docstring with <brackets>. -Sometimes, we have such things on their own, but they may -also appear in code blocks, like - -```starlark -foo = "<thing>" -``` +This rule runs checks on <angle brackets>. **PARAMETERS** @@ -77,16 +62,15 @@ foo = "<thing>" | Name | Description | Default Value | | :------------- | :------------- | :------------- | -| <a id="bracket_function-param"></a>param | an arg with **formatted** docstring, `<default>` by default. | `"<default>"` | -| <a id="bracket_function-md_string"></a>md_string | A markdown string. | ``"foo `1<<10` bar"`` | +| <a id="bracket_function-param"></a>param | an arg with **formatted** docstring, <default> by default. | <code>"<default>"</code> | **RETURNS** -some \<angled> brackets +some <angled> brackets **DEPRECATED** -deprecated for \<reasons> as well as `<reasons>`. +deprecated for <reasons> <a id="bracket_aspect"></a> @@ -97,13 +81,7 @@ deprecated for \<reasons> as well as `<reasons>`. bracket_aspect(<a href="#bracket_aspect-name">name</a>, <a href="#bracket_aspect-brackets">brackets</a>) </pre> -Aspect. - -Sometimes, we want a code block like -```starlark -foo = "<brackets>" -``` -which includes angle brackets. +Aspect with <brackets> **ASPECT ATTRIBUTES** @@ -118,7 +96,7 @@ which includes angle brackets. | 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 \<brackets> | String | optional | `"<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 <brackets> | String | optional | <code>"<default>"</code> | diff --git a/test/testdata/angle_bracket_test/input.bzl b/test/testdata/angle_bracket_test/input.bzl index 0915215..4df0e1f 100644 --- a/test/testdata/angle_bracket_test/input.bzl +++ b/test/testdata/angle_bracket_test/input.bzl @@ -1,45 +1,29 @@ -"""Input file to test angle bracket bug (https://github.com/bazelbuild/skydoc/issues/186) +"""Input file to test <angle bracket bugs> -See https://github.com/bazelbuild/skydoc/issues/186, -https://github.com/bazelbuild/stardoc/issues/132, -and https://github.com/bazelbuild/stardoc/issues/137. +See https://github.com/bazelbuild/skydoc/issues/186 +and https://github.com/bazelbuild/stardoc/issues/132""" -<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 (`<` becomes <). -Angle brackets are also preserved in inline code blocks (`#include <vector>`). -""" +def bracket_function(param = "<default>"): + """Dummy docstring with <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>" - ``` + This rule runs checks on <angle brackets>. Args: - param: an arg with **formatted** docstring, `<default>` by default. - md_string: A markdown string. + param: an arg with **formatted** docstring, <default> by default. Returns: - some \\<angled> brackets + some <angled> brackets Deprecated: - deprecated for \\<reasons> as well as `<reasons>`. + deprecated for <reasons> """ - return param or md_string + return param # buildifier: disable=unsorted-dict-items bracketuse = provider( - doc = "Information with \\<brackets>", + doc = "Information with <brackets>", fields = { - "foo": "A string representing \\<foo>", + "foo": "A string representing <foo>", "bar": "A string representing bar", "baz": "A string representing baz", }, @@ -51,19 +35,11 @@ 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>", - ), - "also_useless": attr.string( - doc = """Args with some formatted tags: `<tag>` and -```xml -<tag2>x</tag2> -``` -""", - default = "1<<5", + doc = "Args with some tags: <tag1>, <tag2>", + default = "Find <brackets>", ), }, ) @@ -74,18 +50,11 @@ def _bracket_aspect_impl(ctx): bracket_aspect = aspect( implementation = _bracket_aspect_impl, - doc = """Aspect. - -Sometimes, we want a code block like -```starlark -foo = "<brackets>" -``` -which includes angle brackets. -""", + doc = "Aspect with <brackets>", attr_aspects = ["deps"], attrs = { "brackets": attr.string( - doc = "Attribute with \\<brackets>", + doc = "Attribute with <brackets>", default = "<default>", ), }, diff --git a/test/testdata/angle_bracket_test/legacy_golden.md b/test/testdata/angle_bracket_test/legacy_golden.md deleted file mode 100644 index 42f8fc6..0000000 --- a/test/testdata/angle_bracket_test/legacy_golden.md +++ /dev/null @@ -1,124 +0,0 @@ -<!-- Generated with Stardoc: http://skydoc.bazel.build --> - -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 (`<` becomes <). -Angle brackets are also preserved in inline code blocks (`#include <vector>`). - -<a id="my_anglebrac"></a> - -## my_anglebrac - -<pre> -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 \<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-also_useless"></a>also_useless | Args with some formatted tags: `<tag>` and <pre><code class="language-xml"><tag2>x</tag2></code></pre> | String | optional | `"1<<5"` | -| <a id="my_anglebrac-useless"></a>useless | Args with some tags: \<tag1>, \<tag2> | String | optional | `"Find \<brackets>"` | - - -<a id="bracketuse"></a> - -## bracketuse - -<pre> -bracketuse(<a href="#bracketuse-foo">foo</a>, <a href="#bracketuse-bar">bar</a>, <a href="#bracketuse-baz">baz</a>) -</pre> - -Information with \<brackets> - -**FIELDS** - - -| Name | Description | -| :------------- | :------------- | -| <a id="bracketuse-foo"></a>foo | A string representing \<foo> | -| <a id="bracketuse-bar"></a>bar | A string representing bar | -| <a id="bracketuse-baz"></a>baz | A string representing baz | - - -<a id="bracket_function"></a> - -## bracket_function - -<pre> -bracket_function(<a href="#bracket_function-param">param</a>, <a href="#bracket_function-md_string">md_string</a>) -</pre> - -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>" -``` - - -**PARAMETERS** - - -| Name | Description | Default Value | -| :------------- | :------------- | :------------- | -| <a id="bracket_function-param"></a>param | an arg with **formatted** docstring, `<default>` by default. | `"<default>"` | -| <a id="bracket_function-md_string"></a>md_string | A markdown string. | ``"foo `1<<10` bar"`` | - -**RETURNS** - -some \<angled> brackets - -**DEPRECATED** - -deprecated for \<reasons> as well as `<reasons>`. - - -<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. - -Sometimes, we want a code block like -```starlark -foo = "<brackets>" -``` -which includes angle brackets. - -**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 \<brackets> | String | optional | `"<default>"` | - - diff --git a/test/testdata/apple_basic_test/golden.md b/test/testdata/apple_basic_test/golden.md index b9e7a5b..5a9eb6e 100644..100755 --- a/test/testdata/apple_basic_test/golden.md +++ b/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 | | diff --git a/test/testdata/aspect_test/golden.md b/test/testdata/aspect_test/golden.md index e1ef986..92e62cc 100644..100755 --- a/test/testdata/aspect_test/golden.md +++ b/test/testdata/aspect_test/golden.md @@ -28,9 +28,7 @@ my_aspect_impl(<a href="#my_aspect_impl-ctx">ctx</a>) my_aspect(<a href="#my_aspect-name">name</a>, <a href="#my_aspect-first">first</a>, <a href="#my_aspect-second">second</a>) </pre> -This is my aspect. - -It does stuff. +This is my aspect. It does stuff. **ASPECT ATTRIBUTES** @@ -46,9 +44,9 @@ 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 | - | <a href="https://bazel.build/concepts/labels">Label</a> | required | | +| <a id="my_aspect-second"></a>second | - | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required | | <a id="other_aspect"></a> @@ -64,13 +62,17 @@ This is another aspect. **ASPECT ATTRIBUTES** +| Name | Type | +| :------------- | :------------- | +| *| String | + **ATTRIBUTES** | 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 | | diff --git a/test/testdata/aspect_test/input.bzl b/test/testdata/aspect_test/input.bzl index 38ddde0..72e35a5 100644 --- a/test/testdata/aspect_test/input.bzl +++ b/test/testdata/aspect_test/input.bzl @@ -6,15 +6,11 @@ def my_aspect_impl(ctx): my_aspect = aspect( implementation = my_aspect_impl, - doc = """ - This is my aspect. - - It does stuff. - """, + doc = "This is my aspect. It does stuff.", attr_aspects = ["deps", "attr_aspect"], attrs = { - "first": attr.bool(mandatory = True), - "second": attr.string(mandatory = True), + "first": attr.label(mandatory = True, allow_single_file = True), + "second": attr.string_dict(mandatory = True), }, ) diff --git a/test/testdata/aspect_test/legacy_golden.md b/test/testdata/aspect_test/legacy_golden.md deleted file mode 100644 index 283689a..0000000 --- a/test/testdata/aspect_test/legacy_golden.md +++ /dev/null @@ -1,80 +0,0 @@ -<!-- Generated with Stardoc: http://skydoc.bazel.build --> - -The input file for the aspect test - -<a id="my_aspect_impl"></a> - -## my_aspect_impl - -<pre> -my_aspect_impl(<a href="#my_aspect_impl-ctx">ctx</a>) -</pre> - - - -**PARAMETERS** - - -| Name | Description | Default Value | -| :------------- | :------------- | :------------- | -| <a id="my_aspect_impl-ctx"></a>ctx | <p align="center"> - </p> | none | - - -<a id="my_aspect"></a> - -## my_aspect - -<pre> -my_aspect(<a href="#my_aspect-name">name</a>, <a href="#my_aspect-first">first</a>, <a href="#my_aspect-second">second</a>) -</pre> - -This is my aspect. - -It does stuff. - -**ASPECT ATTRIBUTES** - - -| Name | Type | -| :------------- | :------------- | -| deps| String | -| attr_aspect| String | - - -**ATTRIBUTES** - - -| 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="other_aspect"></a> - -## other_aspect - -<pre> -other_aspect(<a href="#other_aspect-name">name</a>, <a href="#other_aspect-third">third</a>) -</pre> - -This is another aspect. - -**ASPECT ATTRIBUTES** - - -| Name | Type | -| :------------- | :------------- | -| *| String | - - -**ATTRIBUTES** - - -| 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 | | - - diff --git a/test/testdata/attribute_defaults_test/golden.md b/test/testdata/attribute_defaults_test/golden.md index 64adeab..ae62b4c 100644..100755 --- a/test/testdata/attribute_defaults_test/golden.md +++ b/test/testdata/attribute_defaults_test/golden.md @@ -18,16 +18,16 @@ This is my rule. It does stuff. | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | <a id="my_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | -| <a id="my_rule-a"></a>a | Some bool | Boolean | optional | `False` | -| <a id="my_rule-b"></a>b | Some int | Integer | optional | `2` | -| <a id="my_rule-c"></a>c | Some int_list | List of integers | optional | `[0, 1]` | -| <a id="my_rule-d"></a>d | Some label | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `"@io_bazel_stardoc//foo:bar"` | -| <a id="my_rule-e"></a>e | Some label_keyed_string_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: Label -> String</a> | optional | `{"@io_bazel_stardoc//foo:bar": "hello", "@io_bazel_stardoc//bar:baz": "goodbye"}` | -| <a id="my_rule-f"></a>f | Some label_list | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `["@io_bazel_stardoc//foo:bar", "@io_bazel_stardoc//bar:baz"]` | -| <a id="my_rule-g"></a>g | Some string | String | optional | `""` | -| <a id="my_rule-h"></a>h | Some string_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | `{"animal": "bunny", "color": "orange"}` | -| <a id="my_rule-i"></a>i | Some string_list | List of strings | optional | `["cat", "dog"]` | -| <a id="my_rule-j"></a>j | Some string_list_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> List of strings</a> | optional | `{"animal": ["cat", "bunny"], "color": ["blue", "orange"]}` | +| <a id="my_rule-a"></a>a | Some bool | Boolean | optional | <code>False</code> | +| <a id="my_rule-b"></a>b | Some int | Integer | optional | <code>2</code> | +| <a id="my_rule-c"></a>c | Some int_list | List of integers | optional | <code>[0, 1]</code> | +| <a id="my_rule-d"></a>d | Some label | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>//foo:bar</code> | +| <a id="my_rule-e"></a>e | Some label_keyed_string_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: Label -> String</a> | optional | <code>{"//foo:bar": "hello", "//bar:baz": "goodbye"}</code> | +| <a id="my_rule-f"></a>f | Some label_list | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>["//foo:bar", "//bar:baz"]</code> | +| <a id="my_rule-g"></a>g | Some string | String | optional | <code>""</code> | +| <a id="my_rule-h"></a>h | Some string_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | <code>{"animal": "bunny", "color": "orange"}</code> | +| <a id="my_rule-i"></a>i | Some string_list | List of strings | optional | <code>["cat", "dog"]</code> | +| <a id="my_rule-j"></a>j | Some string_list_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> List of strings</a> | optional | <code>{"animal": ["cat", "bunny"], "color": ["blue", "orange"]}</code> | | <a id="my_rule-k"></a>k | Some bool | Boolean | required | | | <a id="my_rule-l"></a>l | Some int | Integer | required | | | <a id="my_rule-m"></a>m | Some int_list | List of integers | required | | @@ -38,9 +38,9 @@ This is my rule. It does stuff. | <a id="my_rule-r"></a>r | Some string_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required | | | <a id="my_rule-s"></a>s | Some string_list | List of strings | required | | | <a id="my_rule-t"></a>t | Some string_list_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> List of strings</a> | required | | -| <a id="my_rule-u"></a>u | - | String | optional | `""` | -| <a id="my_rule-v"></a>v | - | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` | -| <a id="my_rule-w"></a>w | - | Integer | optional | `0` | +| <a id="my_rule-u"></a>u | - | String | optional | <code>""</code> | +| <a id="my_rule-v"></a>v | - | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>None</code> | +| <a id="my_rule-w"></a>w | - | Integer | optional | <code>0</code> | <a id="my_aspect"></a> @@ -67,8 +67,8 @@ 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-y"></a>y | some string | String | optional | `"why"` | -| <a id="my_aspect-z"></a>z | - | 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-y"></a>y | some string | String | optional | <code>"why"</code> | +| <a id="my_aspect-z"></a>z | - | String | required | | diff --git a/test/testdata/attribute_defaults_test/input.bzl b/test/testdata/attribute_defaults_test/input.bzl index 9812790..3b531b3 100644 --- a/test/testdata/attribute_defaults_test/input.bzl +++ b/test/testdata/attribute_defaults_test/input.bzl @@ -14,7 +14,7 @@ my_aspect = aspect( doc = "This is my aspect. It does stuff.", attr_aspects = ["deps", "attr_aspect"], attrs = { - "_x": attr.label(mandatory = True, default = "//foo:bar"), + "_x": attr.label(mandatory = True), "y": attr.string(default = "why", doc = "some string"), "z": attr.string(mandatory = True), }, diff --git a/test/testdata/attribute_defaults_test/legacy_golden.md b/test/testdata/attribute_defaults_test/legacy_golden.md deleted file mode 100644 index 4eaf4b9..0000000 --- a/test/testdata/attribute_defaults_test/legacy_golden.md +++ /dev/null @@ -1,74 +0,0 @@ -<!-- Generated with Stardoc: http://skydoc.bazel.build --> - -A golden test to verify attribute default values. - -<a id="my_rule"></a> - -## my_rule - -<pre> -my_rule(<a href="#my_rule-name">name</a>, <a href="#my_rule-a">a</a>, <a href="#my_rule-b">b</a>, <a href="#my_rule-c">c</a>, <a href="#my_rule-d">d</a>, <a href="#my_rule-e">e</a>, <a href="#my_rule-f">f</a>, <a href="#my_rule-g">g</a>, <a href="#my_rule-h">h</a>, <a href="#my_rule-i">i</a>, <a href="#my_rule-j">j</a>, <a href="#my_rule-k">k</a>, <a href="#my_rule-l">l</a>, <a href="#my_rule-m">m</a>, <a href="#my_rule-n">n</a>, <a href="#my_rule-o">o</a>, <a href="#my_rule-p">p</a>, <a href="#my_rule-q">q</a>, <a href="#my_rule-r">r</a>, <a href="#my_rule-s">s</a>, <a href="#my_rule-t">t</a>, <a href="#my_rule-u">u</a>, <a href="#my_rule-v">v</a>, <a href="#my_rule-w">w</a>) -</pre> - -This is my rule. It does stuff. - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| <a id="my_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | -| <a id="my_rule-a"></a>a | Some bool | Boolean | optional | `False` | -| <a id="my_rule-b"></a>b | Some int | Integer | optional | `2` | -| <a id="my_rule-c"></a>c | Some int_list | List of integers | optional | `[0, 1]` | -| <a id="my_rule-d"></a>d | Some label | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `//foo:bar` | -| <a id="my_rule-e"></a>e | Some label_keyed_string_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: Label -> String</a> | optional | `{"//foo:bar": "hello", "//bar:baz": "goodbye"}` | -| <a id="my_rule-f"></a>f | Some label_list | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `["//foo:bar", "//bar:baz"]` | -| <a id="my_rule-g"></a>g | Some string | String | optional | `""` | -| <a id="my_rule-h"></a>h | Some string_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | `{"animal": "bunny", "color": "orange"}` | -| <a id="my_rule-i"></a>i | Some string_list | List of strings | optional | `["cat", "dog"]` | -| <a id="my_rule-j"></a>j | Some string_list_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> List of strings</a> | optional | `{"animal": ["cat", "bunny"], "color": ["blue", "orange"]}` | -| <a id="my_rule-k"></a>k | Some bool | Boolean | required | | -| <a id="my_rule-l"></a>l | Some int | Integer | required | | -| <a id="my_rule-m"></a>m | Some int_list | List of integers | required | | -| <a id="my_rule-n"></a>n | Some label | <a href="https://bazel.build/concepts/labels">Label</a> | required | | -| <a id="my_rule-o"></a>o | Some label_keyed_string_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: Label -> String</a> | required | | -| <a id="my_rule-p"></a>p | Some label_list | <a href="https://bazel.build/concepts/labels">List of labels</a> | required | | -| <a id="my_rule-q"></a>q | Some string | String | required | | -| <a id="my_rule-r"></a>r | Some string_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required | | -| <a id="my_rule-s"></a>s | Some string_list | List of strings | required | | -| <a id="my_rule-t"></a>t | Some string_list_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> List of strings</a> | required | | -| <a id="my_rule-u"></a>u | - | String | optional | `""` | -| <a id="my_rule-v"></a>v | - | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` | -| <a id="my_rule-w"></a>w | - | Integer | optional | `0` | - - -<a id="my_aspect"></a> - -## my_aspect - -<pre> -my_aspect(<a href="#my_aspect-name">name</a>, <a href="#my_aspect-y">y</a>, <a href="#my_aspect-z">z</a>) -</pre> - -This is my aspect. It does stuff. - -**ASPECT ATTRIBUTES** - - -| Name | Type | -| :------------- | :------------- | -| deps| String | -| attr_aspect| String | - - -**ATTRIBUTES** - - -| 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-y"></a>y | some string | String | optional | `"why"` | -| <a id="my_aspect-z"></a>z | - | String | required | | - - diff --git a/test/testdata/attribute_types_test/golden.md b/test/testdata/attribute_types_test/golden.md index 1412f2f..9a988c1 100644..100755 --- a/test/testdata/attribute_types_test/golden.md +++ b/test/testdata/attribute_types_test/golden.md @@ -10,9 +10,7 @@ my_rule(<a href="#my_rule-name">name</a>, <a href="#my_rule-a">a</a>, <a href="#my_rule-b">b</a>, <a href="#my_rule-c">c</a>, <a href="#my_rule-d">d</a>, <a href="#my_rule-e">e</a>, <a href="#my_rule-f">f</a>, <a href="#my_rule-g">g</a>, <a href="#my_rule-h">h</a>, <a href="#my_rule-i">i</a>, <a href="#my_rule-j">j</a>, <a href="#my_rule-k">k</a>, <a href="#my_rule-l">l</a>) </pre> -This is my rule. - -It does stuff. +This is my rule. It does stuff. **ATTRIBUTES** @@ -26,11 +24,11 @@ It does stuff. | <a id="my_rule-d"></a>d | Some label | <a href="https://bazel.build/concepts/labels">Label</a> | required | | | <a id="my_rule-e"></a>e | Some label_keyed_string_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: Label -> String</a> | required | | | <a id="my_rule-f"></a>f | Some label_list | <a href="https://bazel.build/concepts/labels">List of labels</a> | required | | -| <a id="my_rule-g"></a>g | Some output | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` | -| <a id="my_rule-h"></a>h | Some output_list | List of labels | optional | `[]` | +| <a id="my_rule-g"></a>g | Some output | <a href="https://bazel.build/concepts/labels">Label</a> | optional | | +| <a id="my_rule-h"></a>h | Some output_list | List of labels | optional | | | <a id="my_rule-i"></a>i | Some string | String | required | | | <a id="my_rule-j"></a>j | Some string_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required | | | <a id="my_rule-k"></a>k | Some string_list | List of strings | required | | -| <a id="my_rule-l"></a>l | Some string_list_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> List of strings</a> | optional | `{}` | +| <a id="my_rule-l"></a>l | Some string_list_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> List of strings</a> | optional | <code>{}</code> | diff --git a/test/testdata/attribute_types_test/input.bzl b/test/testdata/attribute_types_test/input.bzl index 3c1e8d5..92c037c 100644 --- a/test/testdata/attribute_types_test/input.bzl +++ b/test/testdata/attribute_types_test/input.bzl @@ -6,11 +6,7 @@ def my_rule_impl(ctx): my_rule = rule( implementation = my_rule_impl, - doc = """ - This is my rule. - - It does stuff. - """, + doc = "This is my rule. It does stuff.", attrs = { "a": attr.bool(mandatory = True, doc = "Some bool"), "b": attr.int(mandatory = True, doc = "Some int"), diff --git a/test/testdata/attribute_types_test/legacy_golden.md b/test/testdata/attribute_types_test/legacy_golden.md deleted file mode 100644 index aa2ae91..0000000 --- a/test/testdata/attribute_types_test/legacy_golden.md +++ /dev/null @@ -1,36 +0,0 @@ -<!-- Generated with Stardoc: http://skydoc.bazel.build --> - - - -<a id="my_rule"></a> - -## my_rule - -<pre> -my_rule(<a href="#my_rule-name">name</a>, <a href="#my_rule-a">a</a>, <a href="#my_rule-b">b</a>, <a href="#my_rule-c">c</a>, <a href="#my_rule-d">d</a>, <a href="#my_rule-e">e</a>, <a href="#my_rule-f">f</a>, <a href="#my_rule-g">g</a>, <a href="#my_rule-h">h</a>, <a href="#my_rule-i">i</a>, <a href="#my_rule-j">j</a>, <a href="#my_rule-k">k</a>, <a href="#my_rule-l">l</a>) -</pre> - -This is my rule. - -It does stuff. - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| <a id="my_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | -| <a id="my_rule-a"></a>a | Some bool | Boolean | required | | -| <a id="my_rule-b"></a>b | Some int | Integer | required | | -| <a id="my_rule-c"></a>c | Some int_list | List of integers | required | | -| <a id="my_rule-d"></a>d | Some label | <a href="https://bazel.build/concepts/labels">Label</a> | required | | -| <a id="my_rule-e"></a>e | Some label_keyed_string_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: Label -> String</a> | required | | -| <a id="my_rule-f"></a>f | Some label_list | <a href="https://bazel.build/concepts/labels">List of labels</a> | required | | -| <a id="my_rule-g"></a>g | Some output | <a href="https://bazel.build/concepts/labels">Label</a> | optional | | -| <a id="my_rule-h"></a>h | Some output_list | List of labels | optional | | -| <a id="my_rule-i"></a>i | Some string | String | required | | -| <a id="my_rule-j"></a>j | Some string_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required | | -| <a id="my_rule-k"></a>k | Some string_list | List of strings | required | | -| <a id="my_rule-l"></a>l | Some string_list_dict | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> List of strings</a> | optional | `{}` | - - diff --git a/test/testdata/cc_api_test/golden.md b/test/testdata/cc_api_test/golden.md index 183402e..10ca7f8 100644..100755 --- a/test/testdata/cc_api_test/golden.md +++ b/test/testdata/cc_api_test/golden.md @@ -19,7 +19,7 @@ This rule does C++-related things. | :------------- | :------------- | :------------- | :------------- | :------------- | | <a id="cpp_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="cpp_related_rule-first"></a>first | - | <a href="https://bazel.build/concepts/labels">Label</a> | required | | -| <a id="cpp_related_rule-fourth"></a>fourth | - | Boolean | optional | `False` | +| <a id="cpp_related_rule-fourth"></a>fourth | - | Boolean | optional | <code>False</code> | | <a id="cpp_related_rule-second"></a>second | - | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required | | | <a id="cpp_related_rule-third"></a>third | - | <a href="https://bazel.build/concepts/labels">Label</a> | required | | diff --git a/test/testdata/config_apis_test/golden.md b/test/testdata/config_apis_test/golden.md index e1d5fdf..e1d5fdf 100644..100755 --- a/test/testdata/config_apis_test/golden.md +++ b/test/testdata/config_apis_test/golden.md diff --git a/test/testdata/config_apis_test/input.bzl b/test/testdata/config_apis_test/input.bzl index d5b3c2f..fb2a8ce 100644 --- a/test/testdata/config_apis_test/input.bzl +++ b/test/testdata/config_apis_test/input.bzl @@ -1,7 +1,7 @@ # buildifier: disable=module-docstring # buildifier: disable=function-docstring def exercise_the_api(): - _unused = configuration_field(fragment = "cpp", name = "custom_malloc") # @unused + _var6 = configuration_field("foo", "bar") # @unused exercise_the_api() diff --git a/test/testdata/cpp_basic_test/golden.md b/test/testdata/cpp_basic_test/golden.md index abce00a..7061e26 100644..100755 --- a/test/testdata/cpp_basic_test/golden.md +++ b/test/testdata/cpp_basic_test/golden.md @@ -19,7 +19,7 @@ This rule does cpp-related things. | :------------- | :------------- | :------------- | :------------- | :------------- | | <a id="cpp_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="cpp_related_rule-first"></a>first | - | <a href="https://bazel.build/concepts/labels">Label</a> | required | | -| <a id="cpp_related_rule-fourth"></a>fourth | - | Boolean | optional | `False` | +| <a id="cpp_related_rule-fourth"></a>fourth | - | Boolean | optional | <code>False</code> | | <a id="cpp_related_rule-second"></a>second | - | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required | | | <a id="cpp_related_rule-third"></a>third | - | <a href="https://bazel.build/concepts/labels">Label</a> | required | | diff --git a/test/testdata/filter_rules_test/golden.md b/test/testdata/filter_rules_test/golden.md index 2801a16..7e85581 100644..100755 --- a/test/testdata/filter_rules_test/golden.md +++ b/test/testdata/filter_rules_test/golden.md @@ -2,43 +2,43 @@ -<a id="allowlisted_dep_rule"></a> +<a id="my_rule"></a> -## allowlisted_dep_rule +## my_rule <pre> -allowlisted_dep_rule(<a href="#allowlisted_dep_rule-name">name</a>, <a href="#allowlisted_dep_rule-first">first</a>, <a href="#allowlisted_dep_rule-second">second</a>) +my_rule(<a href="#my_rule-name">name</a>, <a href="#my_rule-first">first</a>, <a href="#my_rule-second">second</a>) </pre> -This is the dep rule. It does stuff. +This is my rule. It does stuff. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | -| <a id="allowlisted_dep_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | -| <a id="allowlisted_dep_rule-first"></a>first | dep's my_rule doc string | <a href="https://bazel.build/concepts/labels">Label</a> | required | | -| <a id="allowlisted_dep_rule-second"></a>second | - | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required | | +| <a id="my_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | +| <a id="my_rule-first"></a>first | first my_rule doc string | <a href="https://bazel.build/concepts/labels">Label</a> | required | | +| <a id="my_rule-second"></a>second | - | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required | | -<a id="my_rule"></a> +<a id="whitelisted_dep_rule"></a> -## my_rule +## whitelisted_dep_rule <pre> -my_rule(<a href="#my_rule-name">name</a>, <a href="#my_rule-first">first</a>, <a href="#my_rule-second">second</a>) +whitelisted_dep_rule(<a href="#whitelisted_dep_rule-name">name</a>, <a href="#whitelisted_dep_rule-first">first</a>, <a href="#whitelisted_dep_rule-second">second</a>) </pre> -This is my rule. It does stuff. +This is the dep rule. It does stuff. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | -| <a id="my_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | -| <a id="my_rule-first"></a>first | first my_rule doc string | <a href="https://bazel.build/concepts/labels">Label</a> | required | | -| <a id="my_rule-second"></a>second | - | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required | | +| <a id="whitelisted_dep_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | +| <a id="whitelisted_dep_rule-first"></a>first | dep's my_rule doc string | <a href="https://bazel.build/concepts/labels">Label</a> | required | | +| <a id="whitelisted_dep_rule-second"></a>second | - | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required | | diff --git a/test/testdata/filter_rules_test/input.bzl b/test/testdata/filter_rules_test/input.bzl index 08cc012..5d05b9b 100644 --- a/test/testdata/filter_rules_test/input.bzl +++ b/test/testdata/filter_rules_test/input.bzl @@ -1,10 +1,13 @@ # buildifier: disable=module-docstring load( ":testdata/filter_rules_test/dep.bzl", - "my_rule_impl", dep_rule = "my_rule", ) +def my_rule_impl(ctx): + _ignore = [ctx] # @unused + return [] + my_rule = rule( implementation = my_rule_impl, doc = "This is my rule. It does stuff.", @@ -26,7 +29,7 @@ other_rule = rule( }, ) -allowlisted_dep_rule = dep_rule +whitelisted_dep_rule = dep_rule yet_another_rule = rule( implementation = my_rule_impl, diff --git a/test/testdata/function_basic_test/golden.md b/test/testdata/function_basic_test/golden.md index bf758b1..138f3c2 100644..100755 --- a/test/testdata/function_basic_test/golden.md +++ b/test/testdata/function_basic_test/golden.md @@ -24,12 +24,12 @@ Use `bazel build` to run the check. | :------------- | :------------- | :------------- | | <a id="check_sources-name"></a>name | A unique name for this rule. | none | | <a id="check_sources-required_param"></a>required_param | Use your imagination. | none | -| <a id="check_sources-bool_param"></a>bool_param | <p align="center"> - </p> | `True` | -| <a id="check_sources-srcs"></a>srcs | Source files to run the checks against. | `[]` | -| <a id="check_sources-string_param"></a>string_param | <p align="center"> - </p> | `""` | -| <a id="check_sources-int_param"></a>int_param | Your favorite number. | `2` | -| <a id="check_sources-dict_param"></a>dict_param | <p align="center"> - </p> | `{}` | -| <a id="check_sources-struct_param"></a>struct_param | <p align="center"> - </p> | `struct(foo = "bar")` | +| <a id="check_sources-bool_param"></a>bool_param | <p align="center"> - </p> | <code>True</code> | +| <a id="check_sources-srcs"></a>srcs | Source files to run the checks against. | <code>[]</code> | +| <a id="check_sources-string_param"></a>string_param | <p align="center"> - </p> | <code>""</code> | +| <a id="check_sources-int_param"></a>int_param | Your favorite number. | <code>2</code> | +| <a id="check_sources-dict_param"></a>dict_param | <p align="center"> - </p> | <code>{}</code> | +| <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> @@ -48,24 +48,6 @@ This function is deprecated. Use literally anything but this function. -<a id="param_doc_multiline"></a> - -## param_doc_multiline - -<pre> -param_doc_multiline(<a href="#param_doc_multiline-complex">complex</a>) -</pre> - -Has a complex parameter. - -**PARAMETERS** - - -| Name | Description | Default Value | -| :------------- | :------------- | :------------- | -| <a id="param_doc_multiline-complex"></a>complex | A parameter with some non-obvious behavior.<br><br> For example, it does things that require **multiple paragraphs** to explain.<br><br>Note: we should preserve the nested indent in the following code:<br><br><pre><code class="language-json">{ "key": "value" }</code></pre> | none | - - <a id="returns_a_thing"></a> ## returns_a_thing diff --git a/test/testdata/function_basic_test/input.bzl b/test/testdata/function_basic_test/input.bzl index 2d75025..93bf711 100644 --- a/test/testdata/function_basic_test/input.bzl +++ b/test/testdata/function_basic_test/input.bzl @@ -54,25 +54,6 @@ def deprecated_do_not_use(): """ pass -# buildifier: disable=unused-variable def undocumented_function(a, b, c): - pass - -# buildifier: disable=unused-variable -def param_doc_multiline(complex): - """Has a complex parameter. - - Args: - complex: A parameter with some non-obvious behavior. - - For example, it does things that require **multiple paragraphs** to explain. - - Note: we should preserve the nested indent in the following code: - - ```json - { - "key": "value" - } - ``` - """ + _ignore = [a, b, c] # @unused pass diff --git a/test/testdata/function_wrap_multiple_lines_test/golden.md b/test/testdata/function_wrap_multiple_lines_test/golden.md deleted file mode 100644 index 81f7f9e..0000000 --- a/test/testdata/function_wrap_multiple_lines_test/golden.md +++ /dev/null @@ -1,56 +0,0 @@ -<!-- Generated with Stardoc: http://skydoc.bazel.build --> - -Rules for ANTLR 3. - -<a id="antlr"></a> - -## antlr - -<pre> -antlr(<a href="#antlr-name">name</a>, <a href="#antlr-deps">deps</a>, <a href="#antlr-srcs">srcs</a>, <a href="#antlr-Xconversiontimeout">Xconversiontimeout</a>, <a href="#antlr-Xdbgconversion">Xdbgconversion</a>, <a href="#antlr-Xdbgst">Xdbgst</a>, <a href="#antlr-Xdfa">Xdfa</a>, <a href="#antlr-Xdfaverbose">Xdfaverbose</a>, <a href="#antlr-Xgrtree">Xgrtree</a>, <a href="#antlr-Xm">Xm</a>, - <a href="#antlr-Xmaxdfaedges">Xmaxdfaedges</a>, <a href="#antlr-Xmaxinlinedfastates">Xmaxinlinedfastates</a>, <a href="#antlr-Xminswitchalts">Xminswitchalts</a>, <a href="#antlr-Xmultithreaded">Xmultithreaded</a>, <a href="#antlr-Xnfastates">Xnfastates</a>, <a href="#antlr-Xnocollapse">Xnocollapse</a>, - <a href="#antlr-Xnomergestopstates">Xnomergestopstates</a>, <a href="#antlr-Xnoprune">Xnoprune</a>, <a href="#antlr-XsaveLexer">XsaveLexer</a>, <a href="#antlr-Xwatchconversion">Xwatchconversion</a>, <a href="#antlr-debug">debug</a>, <a href="#antlr-depend">depend</a>, <a href="#antlr-dfa">dfa</a>, <a href="#antlr-dump">dump</a>, <a href="#antlr-imports">imports</a>, - <a href="#antlr-language">language</a>, <a href="#antlr-message_format">message_format</a>, <a href="#antlr-nfa">nfa</a>, <a href="#antlr-package">package</a>, <a href="#antlr-profile">profile</a>, <a href="#antlr-report">report</a>, <a href="#antlr-trace">trace</a>) -</pre> - -Runs [ANTLR 3](https://www.antlr3.org//) on a set of grammars. - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| <a id="antlr-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | -| <a id="antlr-deps"></a>deps | The dependencies to use. Defaults to the most recent ANTLR 3 release, but if you need to use a different version, you can specify the dependencies here. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `["@antlr3_runtimes//:tool"]` | -| <a id="antlr-srcs"></a>srcs | The grammar files to process. | <a href="https://bazel.build/concepts/labels">List of labels</a> | required | | -| <a id="antlr-Xconversiontimeout"></a>Xconversiontimeout | Set NFA conversion timeout for each decision. | Integer | optional | `0` | -| <a id="antlr-Xdbgconversion"></a>Xdbgconversion | Dump lots of info during NFA conversion. | Boolean | optional | `False` | -| <a id="antlr-Xdbgst"></a>Xdbgst | Put tags at start/stop of all templates in output. | Boolean | optional | `False` | -| <a id="antlr-Xdfa"></a>Xdfa | Print DFA as text. | Boolean | optional | `False` | -| <a id="antlr-Xdfaverbose"></a>Xdfaverbose | Generate DFA states in DOT with NFA configs. | Boolean | optional | `False` | -| <a id="antlr-Xgrtree"></a>Xgrtree | Print the grammar AST. | Boolean | optional | `False` | -| <a id="antlr-Xm"></a>Xm | Max number of rule invocations during conversion. | Integer | optional | `0` | -| <a id="antlr-Xmaxdfaedges"></a>Xmaxdfaedges | Max "comfortable" number of edges for single DFA state. | Integer | optional | `0` | -| <a id="antlr-Xmaxinlinedfastates"></a>Xmaxinlinedfastates | Max DFA states before table used rather than inlining. | Integer | optional | `0` | -| <a id="antlr-Xminswitchalts"></a>Xminswitchalts | Don't generate switch() statements for dfas smaller than given number. | Integer | optional | `0` | -| <a id="antlr-Xmultithreaded"></a>Xmultithreaded | Run the analysis in 2 threads. | Boolean | optional | `False` | -| <a id="antlr-Xnfastates"></a>Xnfastates | For nondeterminisms, list NFA states for each path. | Boolean | optional | `False` | -| <a id="antlr-Xnocollapse"></a>Xnocollapse | Collapse incident edges into DFA states. | Boolean | optional | `False` | -| <a id="antlr-Xnomergestopstates"></a>Xnomergestopstates | Max DFA states before table used rather than inlining. | Boolean | optional | `False` | -| <a id="antlr-Xnoprune"></a>Xnoprune | Do not test EBNF block exit branches. | Boolean | optional | `False` | -| <a id="antlr-XsaveLexer"></a>XsaveLexer | For nondeterminisms, list NFA states for each path. | Boolean | optional | `False` | -| <a id="antlr-Xwatchconversion"></a>Xwatchconversion | Don't delete temporary lexers generated from combined grammars. | Boolean | optional | `False` | -| <a id="antlr-debug"></a>debug | Generate a parser that emits debugging events. | Boolean | optional | `False` | -| <a id="antlr-depend"></a>depend | Generate file dependencies; don't actually run antlr. | Boolean | optional | `False` | -| <a id="antlr-dfa"></a>dfa | Generate a DFA for each decision point. | Boolean | optional | `False` | -| <a id="antlr-dump"></a>dump | Print out the grammar without actions. | Boolean | optional | `False` | -| <a id="antlr-imports"></a>imports | The grammar and .tokens files to import. Must be all in the same directory. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | -| <a id="antlr-language"></a>language | The code generation target language. Either C, Cpp, CSharp2, CSharp3, JavaScript, Java, ObjC, Python, Python3 or Ruby (case-sensitive). | String | optional | `""` | -| <a id="antlr-message_format"></a>message_format | Specify output style for messages. | String | optional | `""` | -| <a id="antlr-nfa"></a>nfa | Generate an NFA for each rule. | Boolean | optional | `False` | -| <a id="antlr-package"></a>package | The package/namespace for the generated code. | String | optional | `""` | -| <a id="antlr-profile"></a>profile | Generate a parser that computes profiling information. | Boolean | optional | `False` | -| <a id="antlr-report"></a>report | Print out a report about the grammar(s) processed. | Boolean | optional | `False` | -| <a id="antlr-trace"></a>trace | Generate a parser with trace output. If the default output is not enough, you can override the traceIn and traceOut methods. | Boolean | optional | `False` | - - diff --git a/test/testdata/function_wrap_multiple_lines_test/input.bzl b/test/testdata/function_wrap_multiple_lines_test/input.bzl deleted file mode 100644 index c822551..0000000 --- a/test/testdata/function_wrap_multiple_lines_test/input.bzl +++ /dev/null @@ -1,54 +0,0 @@ -"""Rules for ANTLR 3.""" - -# buildifier: disable=unused-variable -def _generate(ctx): - return None - -antlr = rule( - implementation = _generate, - doc = "Runs [ANTLR 3](https://www.antlr3.org//) on a set of grammars.", - attrs = { - "debug": attr.bool(default = False, doc = "Generate a parser that emits debugging events."), - "depend": attr.bool(default = False, doc = "Generate file dependencies; don't actually run antlr."), - "deps": attr.label_list( - default = [Label("@antlr3_runtimes//:tool")], - doc = """ -The dependencies to use. Defaults to the most recent ANTLR 3 release, -but if you need to use a different version, you can specify the -dependencies here. -""", - ), - "dfa": attr.bool(default = False, doc = "Generate a DFA for each decision point."), - "dump": attr.bool(default = False, doc = "Print out the grammar without actions."), - "imports": attr.label_list(allow_files = True, doc = "The grammar and .tokens files to import. Must be all in the same directory."), - "language": attr.string(doc = "The code generation target language. Either C, Cpp, CSharp2, CSharp3, JavaScript, Java, ObjC, Python, Python3 or Ruby (case-sensitive)."), - "message_format": attr.string(doc = "Specify output style for messages."), - "nfa": attr.bool(default = False, doc = "Generate an NFA for each rule."), - "package": attr.string(doc = "The package/namespace for the generated code."), - "profile": attr.bool(default = False, doc = "Generate a parser that computes profiling information."), - "report": attr.bool(default = False, doc = "Print out a report about the grammar(s) processed."), - "srcs": attr.label_list(allow_files = True, mandatory = True, doc = "The grammar files to process."), - "trace": attr.bool(default = False, doc = "Generate a parser with trace output. If the default output is not enough, you can override the traceIn and traceOut methods."), - "Xconversiontimeout": attr.int(doc = "Set NFA conversion timeout for each decision."), - "Xdbgconversion": attr.bool(default = False, doc = "Dump lots of info during NFA conversion."), - "Xdbgst": attr.bool(default = False, doc = "Put tags at start/stop of all templates in output."), - "Xdfa": attr.bool(default = False, doc = "Print DFA as text."), - "Xdfaverbose": attr.bool(default = False, doc = "Generate DFA states in DOT with NFA configs."), - "Xgrtree": attr.bool(default = False, doc = "Print the grammar AST."), - "Xm": attr.int(doc = "Max number of rule invocations during conversion."), - "Xmaxdfaedges": attr.int(doc = "Max "comfortable" number of edges for single DFA state."), - "Xmaxinlinedfastates": attr.int(doc = "Max DFA states before table used rather than inlining."), - "Xminswitchalts": attr.int(doc = "Don't generate switch() statements for dfas smaller than given number."), - "Xmultithreaded": attr.bool(default = False, doc = "Run the analysis in 2 threads."), - "Xnfastates": attr.bool(default = False, doc = "For nondeterminisms, list NFA states for each path."), - "Xnocollapse": attr.bool(default = False, doc = "Collapse incident edges into DFA states."), - "Xnoprune": attr.bool(default = False, doc = "Do not test EBNF block exit branches."), - "Xnomergestopstates": attr.bool(default = False, doc = "Max DFA states before table used rather than inlining."), - "XsaveLexer": attr.bool(default = False, doc = "For nondeterminisms, list NFA states for each path."), - "Xwatchconversion": attr.bool(default = False, doc = "Don't delete temporary lexers generated from combined grammars."), - "_tool": attr.label( - executable = True, - cfg = "exec", - ), - }, -) diff --git a/test/testdata/function_wrap_multiple_lines_test/legacy_golden.md b/test/testdata/function_wrap_multiple_lines_test/legacy_golden.md deleted file mode 100644 index 817f02b..0000000 --- a/test/testdata/function_wrap_multiple_lines_test/legacy_golden.md +++ /dev/null @@ -1,56 +0,0 @@ -<!-- Generated with Stardoc: http://skydoc.bazel.build --> - -Rules for ANTLR 3. - -<a id="antlr"></a> - -## antlr - -<pre> -antlr(<a href="#antlr-name">name</a>, <a href="#antlr-deps">deps</a>, <a href="#antlr-srcs">srcs</a>, <a href="#antlr-Xconversiontimeout">Xconversiontimeout</a>, <a href="#antlr-Xdbgconversion">Xdbgconversion</a>, <a href="#antlr-Xdbgst">Xdbgst</a>, <a href="#antlr-Xdfa">Xdfa</a>, <a href="#antlr-Xdfaverbose">Xdfaverbose</a>, <a href="#antlr-Xgrtree">Xgrtree</a>, <a href="#antlr-Xm">Xm</a>, - <a href="#antlr-Xmaxdfaedges">Xmaxdfaedges</a>, <a href="#antlr-Xmaxinlinedfastates">Xmaxinlinedfastates</a>, <a href="#antlr-Xminswitchalts">Xminswitchalts</a>, <a href="#antlr-Xmultithreaded">Xmultithreaded</a>, <a href="#antlr-Xnfastates">Xnfastates</a>, <a href="#antlr-Xnocollapse">Xnocollapse</a>, - <a href="#antlr-Xnomergestopstates">Xnomergestopstates</a>, <a href="#antlr-Xnoprune">Xnoprune</a>, <a href="#antlr-XsaveLexer">XsaveLexer</a>, <a href="#antlr-Xwatchconversion">Xwatchconversion</a>, <a href="#antlr-debug">debug</a>, <a href="#antlr-depend">depend</a>, <a href="#antlr-dfa">dfa</a>, <a href="#antlr-dump">dump</a>, <a href="#antlr-imports">imports</a>, - <a href="#antlr-language">language</a>, <a href="#antlr-message_format">message_format</a>, <a href="#antlr-nfa">nfa</a>, <a href="#antlr-package">package</a>, <a href="#antlr-profile">profile</a>, <a href="#antlr-report">report</a>, <a href="#antlr-trace">trace</a>) -</pre> - -Runs [ANTLR 3](https://www.antlr3.org//) on a set of grammars. - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| <a id="antlr-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | -| <a id="antlr-deps"></a>deps | The dependencies to use. Defaults to the most recent ANTLR 3 release, but if you need to use a different version, you can specify the dependencies here. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[Label("@antlr3_runtimes//:tool")]` | -| <a id="antlr-srcs"></a>srcs | The grammar files to process. | <a href="https://bazel.build/concepts/labels">List of labels</a> | required | | -| <a id="antlr-Xconversiontimeout"></a>Xconversiontimeout | Set NFA conversion timeout for each decision. | Integer | optional | `0` | -| <a id="antlr-Xdbgconversion"></a>Xdbgconversion | Dump lots of info during NFA conversion. | Boolean | optional | `False` | -| <a id="antlr-Xdbgst"></a>Xdbgst | Put tags at start/stop of all templates in output. | Boolean | optional | `False` | -| <a id="antlr-Xdfa"></a>Xdfa | Print DFA as text. | Boolean | optional | `False` | -| <a id="antlr-Xdfaverbose"></a>Xdfaverbose | Generate DFA states in DOT with NFA configs. | Boolean | optional | `False` | -| <a id="antlr-Xgrtree"></a>Xgrtree | Print the grammar AST. | Boolean | optional | `False` | -| <a id="antlr-Xm"></a>Xm | Max number of rule invocations during conversion. | Integer | optional | `0` | -| <a id="antlr-Xmaxdfaedges"></a>Xmaxdfaedges | Max "comfortable" number of edges for single DFA state. | Integer | optional | `0` | -| <a id="antlr-Xmaxinlinedfastates"></a>Xmaxinlinedfastates | Max DFA states before table used rather than inlining. | Integer | optional | `0` | -| <a id="antlr-Xminswitchalts"></a>Xminswitchalts | Don't generate switch() statements for dfas smaller than given number. | Integer | optional | `0` | -| <a id="antlr-Xmultithreaded"></a>Xmultithreaded | Run the analysis in 2 threads. | Boolean | optional | `False` | -| <a id="antlr-Xnfastates"></a>Xnfastates | For nondeterminisms, list NFA states for each path. | Boolean | optional | `False` | -| <a id="antlr-Xnocollapse"></a>Xnocollapse | Collapse incident edges into DFA states. | Boolean | optional | `False` | -| <a id="antlr-Xnomergestopstates"></a>Xnomergestopstates | Max DFA states before table used rather than inlining. | Boolean | optional | `False` | -| <a id="antlr-Xnoprune"></a>Xnoprune | Do not test EBNF block exit branches. | Boolean | optional | `False` | -| <a id="antlr-XsaveLexer"></a>XsaveLexer | For nondeterminisms, list NFA states for each path. | Boolean | optional | `False` | -| <a id="antlr-Xwatchconversion"></a>Xwatchconversion | Don't delete temporary lexers generated from combined grammars. | Boolean | optional | `False` | -| <a id="antlr-debug"></a>debug | Generate a parser that emits debugging events. | Boolean | optional | `False` | -| <a id="antlr-depend"></a>depend | Generate file dependencies; don't actually run antlr. | Boolean | optional | `False` | -| <a id="antlr-dfa"></a>dfa | Generate a DFA for each decision point. | Boolean | optional | `False` | -| <a id="antlr-dump"></a>dump | Print out the grammar without actions. | Boolean | optional | `False` | -| <a id="antlr-imports"></a>imports | The grammar and .tokens files to import. Must be all in the same directory. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | -| <a id="antlr-language"></a>language | The code generation target language. Either C, Cpp, CSharp2, CSharp3, JavaScript, Java, ObjC, Python, Python3 or Ruby (case-sensitive). | String | optional | `""` | -| <a id="antlr-message_format"></a>message_format | Specify output style for messages. | String | optional | `""` | -| <a id="antlr-nfa"></a>nfa | Generate an NFA for each rule. | Boolean | optional | `False` | -| <a id="antlr-package"></a>package | The package/namespace for the generated code. | String | optional | `""` | -| <a id="antlr-profile"></a>profile | Generate a parser that computes profiling information. | Boolean | optional | `False` | -| <a id="antlr-report"></a>report | Print out a report about the grammar(s) processed. | Boolean | optional | `False` | -| <a id="antlr-trace"></a>trace | Generate a parser with trace output. If the default output is not enough, you can override the traceIn and traceOut methods. | Boolean | optional | `False` | - - diff --git a/test/testdata/generated_bzl_test/dep.bzl.tpl b/test/testdata/generated_bzl_test/dep.bzl.tpl new file mode 100644 index 0000000..4c8bd78 --- /dev/null +++ b/test/testdata/generated_bzl_test/dep.bzl.tpl @@ -0,0 +1,4 @@ +"""Used to generate dep.bzl""" + +def my_rule_impl(ctx): + return [] diff --git a/test/testdata/generated_bzl_test/golden.md b/test/testdata/generated_bzl_test/golden.md new file mode 100755 index 0000000..bd98967 --- /dev/null +++ b/test/testdata/generated_bzl_test/golden.md @@ -0,0 +1,24 @@ +<!-- Generated with Stardoc: http://skydoc.bazel.build --> + +A direct dependency file of the input file. + +<a id="my_rule"></a> + +## my_rule + +<pre> +my_rule(<a href="#my_rule-name">name</a>, <a href="#my_rule-first">first</a>, <a href="#my_rule-second">second</a>) +</pre> + +This is my rule. It does stuff. + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| <a id="my_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | +| <a id="my_rule-first"></a>first | first my_rule doc string | <a href="https://bazel.build/concepts/labels">Label</a> | required | | +| <a id="my_rule-second"></a>second | - | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required | | + + diff --git a/test/testdata/generated_bzl_test/input.bzl b/test/testdata/generated_bzl_test/input.bzl new file mode 100644 index 0000000..bad15f6 --- /dev/null +++ b/test/testdata/generated_bzl_test/input.bzl @@ -0,0 +1,16 @@ +"""A direct dependency file of the input file.""" + +load(":testdata/generated_bzl_test/dep.bzl", "my_rule_impl") + +my_rule = rule( + implementation = my_rule_impl, + doc = "This is my rule. It does stuff.", + attrs = { + "first": attr.label( + mandatory = True, + doc = "first my_rule doc string", + allow_single_file = True, + ), + "second": attr.string_dict(mandatory = True), + }, +) diff --git a/test/testdata/html_tables_template_test/golden.md b/test/testdata/html_tables_template_test/golden.md index 5ac16a8..e933347 100644..100755 --- a/test/testdata/html_tables_template_test/golden.md +++ b/test/testdata/html_tables_template_test/golden.md @@ -217,7 +217,7 @@ A unique name for this target. <td><code>first</code></td> <td> -Integer; required +<a href="https://bazel.build/concepts/labels">Label</a>; required </td> </tr> diff --git a/test/testdata/html_tables_template_test/input.bzl b/test/testdata/html_tables_template_test/input.bzl index 08c6689..42ca4ac 100644 --- a/test/testdata/html_tables_template_test/input.bzl +++ b/test/testdata/html_tables_template_test/input.bzl @@ -42,7 +42,7 @@ example_aspect = aspect( doc = "Small example of aspect using a markdown template.", attr_aspects = ["deps", "attr_aspect"], attrs = { - "first": attr.int(mandatory = True), + "first": attr.label(mandatory = True, allow_single_file = True), "second": attr.string(doc = "This is the second attribute."), }, ) diff --git a/test/testdata/input_template_test/golden.md b/test/testdata/input_template_test/golden.md index a7a78bc..90e9a5d 100644..100755 --- a/test/testdata/input_template_test/golden.md +++ b/test/testdata/input_template_test/golden.md @@ -132,7 +132,7 @@ This is my aspect. It does stuff. </p> <b> <code>first</code> - String; required + <a href="https://bazel.build/concepts/labels">Label</a>; required </b> diff --git a/test/testdata/input_template_test/input.bzl b/test/testdata/input_template_test/input.bzl index 4de3dd4..d47d025 100644 --- a/test/testdata/input_template_test/input.bzl +++ b/test/testdata/input_template_test/input.bzl @@ -46,6 +46,6 @@ my_aspect = aspect( doc = "This is my aspect. It does stuff.", attr_aspects = ["deps", "attr_aspect"], attrs = { - "first": attr.string(mandatory = True), + "first": attr.label(mandatory = True, allow_single_file = True), }, ) diff --git a/test/testdata/java_basic_test/golden.md b/test/testdata/java_basic_test/golden.md index e98bbd6..a6d0818 100644..100755 --- a/test/testdata/java_basic_test/golden.md +++ b/test/testdata/java_basic_test/golden.md @@ -19,7 +19,7 @@ This rule does java-related things. | :------------- | :------------- | :------------- | :------------- | :------------- | | <a id="java_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="java_related_rule-first"></a>first | - | <a href="https://bazel.build/concepts/labels">Label</a> | required | | -| <a id="java_related_rule-fourth"></a>fourth | - | Boolean | optional | `False` | +| <a id="java_related_rule-fourth"></a>fourth | - | Boolean | optional | <code>False</code> | | <a id="java_related_rule-second"></a>second | - | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required | | | <a id="java_related_rule-third"></a>third | - | <a href="https://bazel.build/concepts/labels">Label</a> | required | | diff --git a/test/testdata/java_basic_test/input.bzl b/test/testdata/java_basic_test/input.bzl index 0f42592..d61141f 100644 --- a/test/testdata/java_basic_test/input.bzl +++ b/test/testdata/java_basic_test/input.bzl @@ -3,6 +3,7 @@ def exercise_the_api(): var1 = java_common.JavaRuntimeInfo # @unused var2 = JavaInfo # @unused + var3 = java_proto_common # @unused exercise_the_api() diff --git a/test/testdata/local_repository_test/input.bzl b/test/testdata/local_repository_test/input.bzl index 7504183..fdd686b 100644 --- a/test/testdata/local_repository_test/input.bzl +++ b/test/testdata/local_repository_test/input.bzl @@ -1,6 +1,6 @@ """A test that verifies documenting functions in an input file under a local_repository.""" -load("@io_bazel_stardoc//test:testdata/fakedeps/dep.bzl", "give_me_five") +load("@io_bazel_stardoc//test/testdata/fakedeps:dep.bzl", "give_me_five") def min(integers): """Returns the minimum of given elements. diff --git a/test/testdata/macro_kwargs_test/golden.md b/test/testdata/macro_kwargs_test/golden.md index 1a9df5b..d2af867 100644..100755 --- a/test/testdata/macro_kwargs_test/golden.md +++ b/test/testdata/macro_kwargs_test/golden.md @@ -44,7 +44,7 @@ Not much else to say. | Name | Description | Default Value | | :------------- | :------------- | :------------- | | <a id="macro_with_both-name"></a>name | The name of the test rule. | none | -| <a id="macro_with_both-number"></a>number | Some number used for important things | `3` | +| <a id="macro_with_both-number"></a>number | Some number used for important things | <code>3</code> | | <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 | @@ -77,7 +77,7 @@ vel mollis eros pellentesque. | :------------- | :------------- | :------------- | | <a id="macro_with_kwargs-name"></a>name | The name of the test rule. | none | | <a id="macro_with_kwargs-config"></a>config | Config to use for my macro | none | -| <a id="macro_with_kwargs-deps"></a>deps | List of my macro's dependencies | `[]` | +| <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** diff --git a/test/testdata/misc_apis_test/golden.md b/test/testdata/misc_apis_test/golden.md index 3e3ef3c..7b94d9f 100644..100755 --- a/test/testdata/misc_apis_test/golden.md +++ b/test/testdata/misc_apis_test/golden.md @@ -7,7 +7,7 @@ ## my_rule <pre> -my_rule(<a href="#my_rule-name">name</a>, <a href="#my_rule-deps">deps</a>, <a href="#my_rule-src">src</a>, <a href="#my_rule-out">out</a>, <a href="#my_rule-extra_arguments">extra_arguments</a>, <a href="#my_rule-tool">tool</a>) +my_rule(<a href="#my_rule-name">name</a>, <a href="#my_rule-deps">deps</a>, <a href="#my_rule-extra_arguments">extra_arguments</a>, <a href="#my_rule-out">out</a>, <a href="#my_rule-src">src</a>, <a href="#my_rule-tool">tool</a>) </pre> This rule exercises some of the build API. @@ -18,11 +18,11 @@ This rule exercises some of the build API. | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | <a id="my_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | -| <a id="my_rule-deps"></a>deps | A list of dependencies. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | -| <a id="my_rule-src"></a>src | The source file. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` | +| <a id="my_rule-deps"></a>deps | A list of dependencies. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | +| <a id="my_rule-extra_arguments"></a>extra_arguments | - | List of strings | optional | <code>[]</code> | | <a id="my_rule-out"></a>out | The output file. | <a href="https://bazel.build/concepts/labels">Label</a> | required | | -| <a id="my_rule-extra_arguments"></a>extra_arguments | - | List of strings | optional | `[]` | -| <a id="my_rule-tool"></a>tool | The location of the tool to use. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `"@io_bazel_stardoc//foo/bar/baz:target"` | +| <a id="my_rule-src"></a>src | The source file. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>None</code> | +| <a id="my_rule-tool"></a>tool | The location of the tool to use. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>//foo/bar/baz:target</code> | <a id="MyInfo"></a> diff --git a/test/testdata/misc_apis_test/legacy_golden.md b/test/testdata/misc_apis_test/legacy_golden.md deleted file mode 100644 index 1a6b867..0000000 --- a/test/testdata/misc_apis_test/legacy_golden.md +++ /dev/null @@ -1,76 +0,0 @@ -<!-- Generated with Stardoc: http://skydoc.bazel.build --> - - - -<a id="my_rule"></a> - -## my_rule - -<pre> -my_rule(<a href="#my_rule-name">name</a>, <a href="#my_rule-deps">deps</a>, <a href="#my_rule-src">src</a>, <a href="#my_rule-out">out</a>, <a href="#my_rule-extra_arguments">extra_arguments</a>, <a href="#my_rule-tool">tool</a>) -</pre> - -This rule exercises some of the build API. - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| <a id="my_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | -| <a id="my_rule-deps"></a>deps | A list of dependencies. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | -| <a id="my_rule-src"></a>src | The source file. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` | -| <a id="my_rule-out"></a>out | The output file. | <a href="https://bazel.build/concepts/labels">Label</a> | required | | -| <a id="my_rule-extra_arguments"></a>extra_arguments | - | List of strings | optional | `[]` | -| <a id="my_rule-tool"></a>tool | The location of the tool to use. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `//foo/bar/baz:target` | - - -<a id="MyInfo"></a> - -## MyInfo - -<pre> -MyInfo(<a href="#MyInfo-foo">foo</a>, <a href="#MyInfo-bar">bar</a>) -</pre> - - - -**FIELDS** - - -| Name | Description | -| :------------- | :------------- | -| <a id="MyInfo-foo"></a>foo | Something foo-related. | -| <a id="MyInfo-bar"></a>bar | Something bar-related. | - - -<a id="exercise_the_api"></a> - -## exercise_the_api - -<pre> -exercise_the_api() -</pre> - - - - - -<a id="my_rule_impl"></a> - -## my_rule_impl - -<pre> -my_rule_impl(<a href="#my_rule_impl-ctx">ctx</a>) -</pre> - - - -**PARAMETERS** - - -| Name | Description | Default Value | -| :------------- | :------------- | :------------- | -| <a id="my_rule_impl-ctx"></a>ctx | <p align="center"> - </p> | none | - - diff --git a/test/testdata/module_extension_test/golden.md b/test/testdata/module_extension_test/golden.md deleted file mode 100644 index addfc77..0000000 --- a/test/testdata/module_extension_test/golden.md +++ /dev/null @@ -1,45 +0,0 @@ -<!-- Generated with Stardoc: http://skydoc.bazel.build --> - -Minimal example of a .bzl file defining a module extension. - -<a id="my_ext"></a> - -## my_ext - -<pre> -my_ext = use_extension("@io_bazel_stardoc//test:testdata/module_extension_test/input.bzl", "my_ext") -my_ext.install(<a href="#my_ext.install-artifacts">artifacts</a>) -my_ext.artifact(<a href="#my_ext.artifact-artifact">artifact</a>, <a href="#my_ext.artifact-group">group</a>) -</pre> - -Minimal example of a module extension. - - -**TAG CLASSES** - -<a id="my_ext.install"></a> - -### install - -Install tag - -**Attributes** - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| <a id="my_ext.install-artifacts"></a>artifacts | Install artifacts | List of strings | optional | `[]` | - -<a id="my_ext.artifact"></a> - -### artifact - -Artifact tag - -**Attributes** - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| <a id="my_ext.artifact-artifact"></a>artifact | Artifact | String | required | | -| <a id="my_ext.artifact-group"></a>group | Group name | String | optional | `"my_group"` | - - diff --git a/test/testdata/module_extension_test/input.bzl b/test/testdata/module_extension_test/input.bzl deleted file mode 100644 index ceffee4..0000000 --- a/test/testdata/module_extension_test/input.bzl +++ /dev/null @@ -1,38 +0,0 @@ -"""Minimal example of a .bzl file defining a module extension.""" - -# buildifier: disable=unused-variable -def _impl(module_ctx): - """No-op""" - pass - -_artifact = tag_class( - doc = "Artifact tag", - attrs = { - "group": attr.string( - doc = "Group name", - default = "my_group", - ), - "artifact": attr.string( - doc = "Artifact", - mandatory = True, - ), - }, -) - -_install = tag_class( - doc = "Install tag", - attrs = { - "artifacts": attr.string_list( - doc = "Install artifacts", - ), - }, -) - -my_ext = module_extension( - implementation = _impl, - doc = "Minimal example of a module extension.", - tag_classes = { - "install": _install, - "artifact": _artifact, - }, -) diff --git a/test/testdata/multi_level_namespace_test/golden.md b/test/testdata/multi_level_namespace_test/golden.md index 3e753c0..85791c9 100644..100755 --- a/test/testdata/multi_level_namespace_test/golden.md +++ b/test/testdata/multi_level_namespace_test/golden.md @@ -2,24 +2,12 @@ A test that verifies documenting a multi-leveled namespace of functions. -<a id="my_namespace.foo.bar.baz"></a> - -## my_namespace.foo.bar.baz - -<pre> -my_namespace.foo.bar.baz() -</pre> - -This function does nothing. - - - -<a id="my_namespace.math.min"></a> +<a id="my_namespace.min"></a> -## my_namespace.math.min +## my_namespace.min <pre> -my_namespace.math.min(<a href="#my_namespace.math.min-integers">integers</a>) +my_namespace.min(<a href="#my_namespace.min-integers">integers</a>) </pre> Returns the minimum of given elements. @@ -29,19 +17,19 @@ Returns the minimum of given elements. | Name | Description | Default Value | | :------------- | :------------- | :------------- | -| <a id="my_namespace.math.min-integers"></a>integers | A list of integers. Must not be empty. | none | +| <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.min"></a> +<a id="my_namespace.math.min"></a> -## my_namespace.min +## my_namespace.math.min <pre> -my_namespace.min(<a href="#my_namespace.min-integers">integers</a>) +my_namespace.math.min(<a href="#my_namespace.math.min-integers">integers</a>) </pre> Returns the minimum of given elements. @@ -51,19 +39,19 @@ Returns the minimum of given elements. | Name | Description | Default Value | | :------------- | :------------- | :------------- | -| <a id="my_namespace.min-integers"></a>integers | A list of integers. Must not be empty. | none | +| <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.one.three.does_nothing"></a> +<a id="my_namespace.foo.bar.baz"></a> -## my_namespace.one.three.does_nothing +## my_namespace.foo.bar.baz <pre> -my_namespace.one.three.does_nothing() +my_namespace.foo.bar.baz() </pre> This function does nothing. @@ -92,3 +80,15 @@ Returns the minimum of given elements. The minimum integer in the given list. +<a id="my_namespace.one.three.does_nothing"></a> + +## my_namespace.one.three.does_nothing + +<pre> +my_namespace.one.three.does_nothing() +</pre> + +This function does nothing. + + + diff --git a/test/testdata/multi_level_namespace_test_with_allowlist/golden.md b/test/testdata/multi_level_namespace_test_with_whitelist/golden.md index f35b10d..1ca1608 100644 --- a/test/testdata/multi_level_namespace_test_with_allowlist/golden.md +++ b/test/testdata/multi_level_namespace_test_with_whitelist/golden.md @@ -1,15 +1,15 @@ <!-- Generated with Stardoc: http://skydoc.bazel.build --> -A test that verifies documenting a multi-leveled namespace of functions with allowlist symbols. -The allowlist symbols should cause everything in my_namespace to to be documented, but only a +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.math.min"></a> +<a id="my_namespace.min"></a> -## my_namespace.math.min +## my_namespace.min <pre> -my_namespace.math.min(<a href="#my_namespace.math.min-integers">integers</a>) +my_namespace.min(<a href="#my_namespace.min-integers">integers</a>) </pre> Returns the minimum of given elements. @@ -19,15 +19,15 @@ Returns the minimum of given elements. | Name | Description | Default Value | | :------------- | :------------- | :------------- | -| <a id="my_namespace.math.min-integers"></a>integers | <p align="center"> - </p> | none | +| <a id="my_namespace.min-integers"></a>integers | <p align="center"> - </p> | none | -<a id="my_namespace.min"></a> +<a id="my_namespace.math.min"></a> -## my_namespace.min +## my_namespace.math.min <pre> -my_namespace.min(<a href="#my_namespace.min-integers">integers</a>) +my_namespace.math.min(<a href="#my_namespace.math.min-integers">integers</a>) </pre> Returns the minimum of given elements. @@ -37,7 +37,7 @@ Returns the minimum of given elements. | Name | Description | Default Value | | :------------- | :------------- | :------------- | -| <a id="my_namespace.min-integers"></a>integers | <p align="center"> - </p> | none | +| <a id="my_namespace.math.min-integers"></a>integers | <p align="center"> - </p> | none | <a id="other_namespace.foo.nothing"></a> diff --git a/test/testdata/multi_level_namespace_test_with_allowlist/input.bzl b/test/testdata/multi_level_namespace_test_with_whitelist/input.bzl index 5146d11..f070309 100644 --- a/test/testdata/multi_level_namespace_test_with_allowlist/input.bzl +++ b/test/testdata/multi_level_namespace_test_with_whitelist/input.bzl @@ -1,5 +1,5 @@ -"""A test that verifies documenting a multi-leveled namespace of functions with allowlist symbols. -The allowlist symbols should cause everything in my_namespace to to be documented, but only a +"""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.""" def _min(integers): diff --git a/test/testdata/multiple_files_test/golden.md b/test/testdata/multiple_files_test/golden.md index 0fab337..0fab337 100644..100755 --- a/test/testdata/multiple_files_test/golden.md +++ b/test/testdata/multiple_files_test/golden.md diff --git a/test/testdata/multiple_rules_test/golden.md b/test/testdata/multiple_rules_test/golden.md index 085fec8..085fec8 100644..100755 --- a/test/testdata/multiple_rules_test/golden.md +++ b/test/testdata/multiple_rules_test/golden.md diff --git a/test/testdata/namespace_test/golden.md b/test/testdata/namespace_test/golden.md index 6e4c453..f840fcf 100644..100755 --- a/test/testdata/namespace_test/golden.md +++ b/test/testdata/namespace_test/golden.md @@ -21,48 +21,48 @@ Asserts the two given lists are not empty. | <a id="my_namespace.assert_non_empty-other_list"></a>other_list | The second list | none | -<a id="my_namespace.join_strings"></a> +<a id="my_namespace.min"></a> -## my_namespace.join_strings +## my_namespace.min <pre> -my_namespace.join_strings(<a href="#my_namespace.join_strings-strings">strings</a>, <a href="#my_namespace.join_strings-delimiter">delimiter</a>) +my_namespace.min(<a href="#my_namespace.min-integers">integers</a>) </pre> -Joins the given strings with a delimiter. +Returns the minimum of given elements. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | -| <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 | `", "` | +| <a id="my_namespace.min-integers"></a>integers | A list of integers. Must not be empty. | none | **RETURNS** -The joined string. +The minimum integer in the given list. -<a id="my_namespace.min"></a> +<a id="my_namespace.join_strings"></a> -## my_namespace.min +## my_namespace.join_strings <pre> -my_namespace.min(<a href="#my_namespace.min-integers">integers</a>) +my_namespace.join_strings(<a href="#my_namespace.join_strings-strings">strings</a>, <a href="#my_namespace.join_strings-delimiter">delimiter</a>) </pre> -Returns the minimum of given elements. +Joins the given strings with a delimiter. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | -| <a id="my_namespace.min-integers"></a>integers | A list of integers. Must not be empty. | none | +| <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 minimum integer in the given list. +The joined string. diff --git a/test/testdata/proto_format_test/golden.binaryproto b/test/testdata/proto_format_test/golden.binaryproto deleted file mode 100644 index ff1d54b..0000000 --- a/test/testdata/proto_format_test/golden.binaryproto +++ /dev/null @@ -1,21 +0,0 @@ - -Õ - -my_exampleSmall example of rule.* -name A unique name for this target. 7 -useless This argument will be ignored.2 -"ignoreme""J - -my_example<@io_bazel_stardoc//test:testdata/proto_format_test/input.bzlÞ -example$Stores information about an example. -fooA string representing foo -barA string representing bar -bazA string representing baz"G -example<@io_bazel_stardoc//test:testdata/proto_format_test/input.bzl– -check_function% -foo A unique name for this rule. ŒRuns some checks on the given function parameter. - -This rule runs checks on a given function parameter. -Use `bazel build` to run the check. -2N -check_function<@io_bazel_stardoc//test:testdata/proto_format_test/input.bzl* Input file for proto format test2<@io_bazel_stardoc//test:testdata/proto_format_test/input.bzl
\ No newline at end of file diff --git a/test/testdata/proto_format_test/legacy_golden.binaryproto b/test/testdata/proto_format_test/golden.raw Binary files differindex d158834..a93d367 100644 --- a/test/testdata/proto_format_test/legacy_golden.binaryproto +++ b/test/testdata/proto_format_test/golden.raw diff --git a/test/testdata/provider_basic_test/golden.md b/test/testdata/provider_basic_test/golden.md index 7029581..a9d76bf 100644..100755 --- a/test/testdata/provider_basic_test/golden.md +++ b/test/testdata/provider_basic_test/golden.md @@ -17,8 +17,8 @@ Stores information about a foo. | Name | Description | | :------------- | :------------- | -| <a id="MyFooInfo-bar"></a>bar | - | -| <a id="MyFooInfo-baz"></a>baz | - | +| <a id="MyFooInfo-bar"></a>bar | (Undocumented) | +| <a id="MyFooInfo-baz"></a>baz | (Undocumented) | <a id="MyPoorlyDocumentedInfo"></a> @@ -43,16 +43,17 @@ MyPoorlyDocumentedInfo() MyVeryDocumentedInfo(<a href="#MyVeryDocumentedInfo-favorite_food">favorite_food</a>, <a href="#MyVeryDocumentedInfo-favorite_color">favorite_color</a>) </pre> -A provider with some really neat documentation. +A provider with some really neat documentation. Look on my works, ye mighty, and despair! + **FIELDS** | Name | Description | | :------------- | :------------- | -| <a id="MyVeryDocumentedInfo-favorite_food"></a>favorite_food | A string representing my favorite food<br><br>Expected to be delicious. | +| <a id="MyVeryDocumentedInfo-favorite_food"></a>favorite_food | A string representing my favorite food | | <a id="MyVeryDocumentedInfo-favorite_color"></a>favorite_color | A string representing my favorite color | diff --git a/test/testdata/provider_basic_test/input.bzl b/test/testdata/provider_basic_test/input.bzl index cc3068d..bb76c0d 100644 --- a/test/testdata/provider_basic_test/input.bzl +++ b/test/testdata/provider_basic_test/input.bzl @@ -10,21 +10,11 @@ MyFooInfo = provider( # buildifier: disable=unsorted-dict-items MyVeryDocumentedInfo = provider( doc = """ - A provider with some really neat documentation. - - Look on my works, ye mighty, and despair! - """, +A provider with some really neat documentation. +Look on my works, ye mighty, and despair! +""", fields = { - "favorite_food": """ - A string representing my favorite food - - Expected to be delicious. - """, + "favorite_food": "A string representing my favorite food", "favorite_color": "A string representing my favorite color", }, ) - -named_providers_are_hashable = { - MyFooInfo: "MyFooInfo is hashable", - MyVeryDocumentedInfo: "So is MyVeryDocumentedInfo", -} diff --git a/test/testdata/provider_basic_test/legacy_golden.md b/test/testdata/provider_basic_test/legacy_golden.md deleted file mode 100644 index 38dd0f6..0000000 --- a/test/testdata/provider_basic_test/legacy_golden.md +++ /dev/null @@ -1,58 +0,0 @@ -<!-- Generated with Stardoc: http://skydoc.bazel.build --> - - - -<a id="MyFooInfo"></a> - -## MyFooInfo - -<pre> -MyFooInfo(<a href="#MyFooInfo-bar">bar</a>, <a href="#MyFooInfo-baz">baz</a>) -</pre> - -Stores information about a foo. - -**FIELDS** - - -| Name | Description | -| :------------- | :------------- | -| <a id="MyFooInfo-bar"></a>bar | (Undocumented) | -| <a id="MyFooInfo-baz"></a>baz | (Undocumented) | - - -<a id="MyPoorlyDocumentedInfo"></a> - -## MyPoorlyDocumentedInfo - -<pre> -MyPoorlyDocumentedInfo() -</pre> - - - -**FIELDS** - - - -<a id="MyVeryDocumentedInfo"></a> - -## MyVeryDocumentedInfo - -<pre> -MyVeryDocumentedInfo(<a href="#MyVeryDocumentedInfo-favorite_food">favorite_food</a>, <a href="#MyVeryDocumentedInfo-favorite_color">favorite_color</a>) -</pre> - -A provider with some really neat documentation. - -Look on my works, ye mighty, and despair! - -**FIELDS** - - -| Name | Description | -| :------------- | :------------- | -| <a id="MyVeryDocumentedInfo-favorite_food"></a>favorite_food | A string representing my favorite food<br><br> Expected to be delicious. | -| <a id="MyVeryDocumentedInfo-favorite_color"></a>favorite_color | A string representing my favorite color | - - diff --git a/test/testdata/providers_for_attributes_test/golden.md b/test/testdata/providers_for_attributes_test/golden.md index a427cf2..24ebf27 100644..100755 --- a/test/testdata/providers_for_attributes_test/golden.md +++ b/test/testdata/providers_for_attributes_test/golden.md @@ -18,12 +18,12 @@ This rule does things. | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | <a id="my_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | -| <a id="my_rule-fifth"></a>fifth | - | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` | -| <a id="my_rule-first"></a>first | this is the first attribute. | <a href="https://bazel.build/rules/lib/dict">Dictionary: Label -> String</a> | optional | `{}` | -| <a id="my_rule-fourth"></a>fourth | - | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` | -| <a id="my_rule-second"></a>second | - | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | -| <a id="my_rule-sixth"></a>sixth | - | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` | -| <a id="my_rule-third"></a>third | - | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` | +| <a id="my_rule-fifth"></a>fifth | - | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>None</code> | +| <a id="my_rule-first"></a>first | this is the first attribute. | <a href="https://bazel.build/rules/lib/dict">Dictionary: Label -> String</a> | optional | <code>{}</code> | +| <a id="my_rule-fourth"></a>fourth | - | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>None</code> | +| <a id="my_rule-second"></a>second | - | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | +| <a id="my_rule-sixth"></a>sixth | - | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>None</code> | +| <a id="my_rule-third"></a>third | - | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>None</code> | <a id="MyProviderInfo"></a> diff --git a/test/testdata/pure_markdown_template_test/golden.md b/test/testdata/pure_markdown_template_test/golden.md deleted file mode 100644 index 62a9327..0000000 --- a/test/testdata/pure_markdown_template_test/golden.md +++ /dev/null @@ -1,92 +0,0 @@ -<!-- Generated with Stardoc: http://skydoc.bazel.build --> - -Input file for markdown template test - -<a id="example_rule"></a> - -## example_rule - -<pre> -example_rule(<a href="#example_rule-name">name</a>, <a href="#example_rule-first">first</a>, <a href="#example_rule-second">second</a>) -</pre> - -Small example of rule using a markdown template. - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| <a id="example_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | -| <a id="example_rule-first"></a>first | This is the first attribute | String | optional | `""` | -| <a id="example_rule-second"></a>second | - | Integer | optional | `2` | - - -<a id="ExampleProviderInfo"></a> - -## ExampleProviderInfo - -<pre> -ExampleProviderInfo(<a href="#ExampleProviderInfo-foo">foo</a>, <a href="#ExampleProviderInfo-bar">bar</a>, <a href="#ExampleProviderInfo-baz">baz</a>) -</pre> - -Small example of provider using a markdown template. - -**FIELDS** - - -| Name | Description | -| :------------- | :------------- | -| <a id="ExampleProviderInfo-foo"></a>foo | A string representing foo | -| <a id="ExampleProviderInfo-bar"></a>bar | A string representing bar | -| <a id="ExampleProviderInfo-baz"></a>baz | A string representing baz | - - -<a id="example_function"></a> - -## example_function - -<pre> -example_function(<a href="#example_function-foo">foo</a>, <a href="#example_function-bar">bar</a>) -</pre> - -Small example of function using a markdown template. - -**PARAMETERS** - - -| Name | Description | Default Value | -| :------------- | :------------- | :------------- | -| <a id="example_function-foo"></a>foo | This parameter does foo related things. | none | -| <a id="example_function-bar"></a>bar | This parameter does bar related things.<br><br>For example, it does things that require **multiple paragraphs** to explain.<br><br>Note: we should preserve the nested indent in the following code:<br><br><pre><code class="language-json">{ "key": "value" }</code></pre> | `"bar"` | - - -<a id="example_aspect"></a> - -## example_aspect - -<pre> -example_aspect(<a href="#example_aspect-name">name</a>, <a href="#example_aspect-first">first</a>, <a href="#example_aspect-second">second</a>) -</pre> - -Small example of aspect using a markdown template. - -**ASPECT ATTRIBUTES** - - -| Name | Type | -| :------------- | :------------- | -| deps| String | -| attr_aspect| String | - - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| <a id="example_aspect-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | -| <a id="example_aspect-first"></a>first | - | String | required | | -| <a id="example_aspect-second"></a>second | This is the second attribute. | String | optional | `""` | - - diff --git a/test/testdata/pure_markdown_template_test/input.bzl b/test/testdata/pure_markdown_template_test/input.bzl deleted file mode 100644 index 61d185d..0000000 --- a/test/testdata/pure_markdown_template_test/input.bzl +++ /dev/null @@ -1,57 +0,0 @@ -"""Input file for markdown template test""" - -# buildifier: disable=unused-variable -def example_function(foo, bar = "bar"): - """Small example of function using a markdown template. - - Args: - foo: This parameter does foo related things. - bar: This parameter does bar related things. - - For example, it does things that require **multiple paragraphs** to explain. - - Note: we should preserve the nested indent in the following code: - - ```json - { - "key": "value" - } - ``` - """ - pass - -ExampleProviderInfo = provider( - doc = "Small example of provider using a markdown template.", - fields = { - "foo": "A string representing foo", - "bar": "A string representing bar", - "baz": "A string representing baz", - }, -) - -# buildifier: disable=unused-variable -def _rule_impl(ctx): - return [] - -example_rule = rule( - implementation = _rule_impl, - doc = "Small example of rule using a markdown template.", - attrs = { - "first": attr.string(doc = "This is the first attribute"), - "second": attr.int(default = 2), - }, -) - -# buildifier: disable=unused-variable -def _aspect_impl(ctx): - return [] - -example_aspect = aspect( - implementation = _aspect_impl, - doc = "Small example of aspect using a markdown template.", - attr_aspects = ["deps", "attr_aspect"], - attrs = { - "first": attr.string(mandatory = True), - "second": attr.string(doc = "This is the second attribute."), - }, -) diff --git a/test/testdata/py_rule_test/golden.md b/test/testdata/py_rule_test/golden.md index d2a8394..0550bf9 100644..100755 --- a/test/testdata/py_rule_test/golden.md +++ b/test/testdata/py_rule_test/golden.md @@ -18,11 +18,11 @@ This rule does python-related things. | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | <a id="py_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="py_related_rule-fifth"></a>fifth | Hey look, its the fifth thing! | Boolean | optional | `True` | +| <a id="py_related_rule-fifth"></a>fifth | Hey look, its the fifth thing! | Boolean | optional | <code>True</code> | | <a id="py_related_rule-first"></a>first | this is the first doc string! | <a href="https://bazel.build/concepts/labels">Label</a> | required | | -| <a id="py_related_rule-fourth"></a>fourth | the fourth doc string. | Boolean | optional | `False` | +| <a id="py_related_rule-fourth"></a>fourth | the fourth doc string. | Boolean | optional | <code>False</code> | | <a id="py_related_rule-second"></a>second | - | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required | | -| <a id="py_related_rule-sixth"></a>sixth | it's the sixth thing. | List of integers | optional | `[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]` | +| <a id="py_related_rule-sixth"></a>sixth | it's the sixth thing. | List of integers | optional | <code>[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]</code> | | <a id="py_related_rule-third"></a>third | - | <a href="https://bazel.build/concepts/labels">Label</a> | required | | diff --git a/test/testdata/repo_rules_test/golden.md b/test/testdata/repo_rules_test/golden.md index de907c7..87391e3 100644..100755 --- a/test/testdata/repo_rules_test/golden.md +++ b/test/testdata/repo_rules_test/golden.md @@ -18,13 +18,7 @@ Minimal example of a repository rule. | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | <a id="my_repo-name"></a>name | A unique name for this repository. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | -| <a id="my_repo-repo_mapping"></a>repo_mapping | In `WORKSPACE` context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.<br><br>For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`).<br><br>This attribute is _not_ supported in `MODULE.bazel` context (when invoking a repository rule inside a module extension's implementation function). | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | | -| <a id="my_repo-useless"></a>useless | This argument will be ignored.<br><br>You don't have to specify it, but you may. | String | optional | `"ignoreme"` | - -**ENVIRONMENT VARIABLES** - -This repository rule depends on the following environment variables: -* `FOO_CC` -* `BAR_PATH` +| <a id="my_repo-repo_mapping"></a>repo_mapping | A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.<p>For example, an entry <code>"@foo": "@bar"</code> declares that, for any time this repository depends on <code>@foo</code> (such as a dependency on <code>@foo//some:target</code>, it should actually resolve that dependency within globally-declared <code>@bar</code> (<code>@bar//some:target</code>). | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required | | +| <a id="my_repo-useless"></a>useless | This argument will be ingored. You don't have to specify it, but you may. | String | optional | <code>"ignoreme"</code> | diff --git a/test/testdata/repo_rules_test/input.bzl b/test/testdata/repo_rules_test/input.bzl index 114c3bc..023d92d 100644 --- a/test/testdata/repo_rules_test/input.bzl +++ b/test/testdata/repo_rules_test/input.bzl @@ -7,12 +7,8 @@ my_repo = repository_rule( doc = "Minimal example of a repository rule.", attrs = { "useless": attr.string( - doc = """This argument will be ignored. - - You don't have to specify it, but you may. - """, + doc = "This argument will be ingored. You don't have to specify it, but you may.", default = "ignoreme", ), }, - environ = ["FOO_CC", "BAR_PATH"], ) diff --git a/test/testdata/repo_rules_test/legacy_golden.md b/test/testdata/repo_rules_test/legacy_golden.md deleted file mode 100644 index d705a32..0000000 --- a/test/testdata/repo_rules_test/legacy_golden.md +++ /dev/null @@ -1,24 +0,0 @@ -<!-- Generated with Stardoc: http://skydoc.bazel.build --> - - - -<a id="my_repo"></a> - -## my_repo - -<pre> -my_repo(<a href="#my_repo-name">name</a>, <a href="#my_repo-repo_mapping">repo_mapping</a>, <a href="#my_repo-useless">useless</a>) -</pre> - -Minimal example of a repository rule. - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| <a id="my_repo-name"></a>name | A unique name for this repository. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | -| <a id="my_repo-repo_mapping"></a>repo_mapping | A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.<p>For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`). | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required | | -| <a id="my_repo-useless"></a>useless | This argument will be ignored.<br><br>You don't have to specify it, but you may. | String | optional | `"ignoreme"` | - - diff --git a/test/testdata/same_level_file_test/golden.md b/test/testdata/same_level_file_test/golden.md index 66b9a97..66b9a97 100644..100755 --- a/test/testdata/same_level_file_test/golden.md +++ b/test/testdata/same_level_file_test/golden.md diff --git a/test/testdata/simple_test/golden.md b/test/testdata/simple_test/golden.md index a5a2e39..b203bd2 100644..100755 --- a/test/testdata/simple_test/golden.md +++ b/test/testdata/simple_test/golden.md @@ -19,7 +19,7 @@ This is my rule. It does stuff. | :------------- | :------------- | :------------- | :------------- | :------------- | | <a id="my_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | | <a id="my_rule-first"></a>first | first doc string | <a href="https://bazel.build/concepts/labels">Label</a> | required | | -| <a id="my_rule-fourth"></a>fourth | fourth doc string | Boolean | optional | `False` | +| <a id="my_rule-fourth"></a>fourth | fourth doc string | Boolean | optional | <code>False</code> | | <a id="my_rule-second"></a>second | - | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required | | | <a id="my_rule-third"></a>third | - | <a href="https://bazel.build/concepts/labels">Label</a> | required | | diff --git a/test/testdata/struct_default_value_test/golden.md b/test/testdata/struct_default_value_test/golden.md index 38f9908..6d07214 100644..100755 --- a/test/testdata/struct_default_value_test/golden.md +++ b/test/testdata/struct_default_value_test/golden.md @@ -18,10 +18,10 @@ Checks the default values of structs. | Name | Description | Default Value | | :------------- | :------------- | :------------- | -| <a id="check_struct_default_values-struct_no_args"></a>struct_no_args | struct with no arguments | `struct()` | -| <a id="check_struct_default_values-struct_arg"></a>struct_arg | struct with one argument | `struct(foo = "bar")` | -| <a id="check_struct_default_values-struct_args"></a>struct_args | struct with multiple arguments | `struct(bar = "foo", foo = "bar")` | -| <a id="check_struct_default_values-struct_int_args"></a>struct_int_args | struct with int arguments | `struct(one = 1, three = 3, two = 2)` | -| <a id="check_struct_default_values-struct_struct_args"></a>struct_struct_args | struct with struct arguments | `struct(multiple = struct(one = 1, three = 3, two = 2), none = struct(), one = struct(foo = "bar"))` | +| <a id="check_struct_default_values-struct_no_args"></a>struct_no_args | struct with no arguments | <code>struct()</code> | +| <a id="check_struct_default_values-struct_arg"></a>struct_arg | struct with one argument | <code>struct(foo = "bar")</code> | +| <a id="check_struct_default_values-struct_args"></a>struct_args | struct with multiple arguments | <code>struct(bar = "foo", foo = "bar")</code> | +| <a id="check_struct_default_values-struct_int_args"></a>struct_int_args | struct with int arguments | <code>struct(one = 1, three = 3, two = 2)</code> | +| <a id="check_struct_default_values-struct_struct_args"></a>struct_struct_args | struct with struct arguments | <code>struct(multiple = struct(one = 1, three = 3, two = 2), none = struct(), one = struct(foo = "bar"))</code> | diff --git a/test/testdata/unknown_name_test/golden.md b/test/testdata/unknown_name_test/golden.md index 8bbe43c..8bbe43c 100644..100755 --- a/test/testdata/unknown_name_test/golden.md +++ b/test/testdata/unknown_name_test/golden.md |