diff --git a/WORKSPACE b/WORKSPACE index 2191a2c2..a424cc18 100644 --- a/WORKSPACE +++ b/WORKSPACE @@ -14,8 +14,8 @@ load("@bazel_tools//tools/build_defs/repo:git.bzl", "git_repository") # Needed for generating the Stardoc release binary. git_repository( name = "io_bazel", - commit = "c2394ca2d201bdc72887b3920680ca119d46a26e", # 2023-05-10 - remote = "https://github.com/bazelbuild/bazel.git", + commit = "3d2604806a9747f317c5b560bbf89cdc1be033ba", # 2023-07-12 + remote = "https://github.com/fmeum/bazel.git", ) # The following binds are needed for building protobuf java libraries. diff --git a/stardoc/proto/stardoc_output.proto b/stardoc/proto/stardoc_output.proto index e35e7141..3512ca00 100644 --- a/stardoc/proto/stardoc_output.proto +++ b/stardoc/proto/stardoc_output.proto @@ -23,9 +23,9 @@ package stardoc_output; option java_package = "com.google.devtools.build.skydoc.rendering.proto"; option java_outer_classname = "StardocOutputProtos"; -// The root output proto of Stardoc. A single invocation of Stardoc will output -// exactly one instance of this proto, representing all documentation for -// the input Starlark file. +// The root output proto of Stardoc. An invocation of Stardoc on a single file +// will output exactly one instance of this proto, representing all +// documentation for the input Starlark file. message ModuleInfo { repeated RuleInfo rule_info = 1; @@ -37,6 +37,15 @@ message ModuleInfo { // The docstring present at the top of the input Starlark file. string module_docstring = 5; + + // The display form of the label of the module file (as seen from the + // starlark_doc_extract or Stardoc target's repo). Unset when there is no + // module file (e.g. when the module is a REPL, or in Bazel's internal tests). + string file = 6; + + repeated ModuleExtensionInfo module_extension_info = 7; + + repeated RepositoryRuleInfo repository_rule_info = 8; } // Representation of a Starlark rule attribute type. These generally @@ -63,7 +72,8 @@ enum AttributeType { // Representation of a Starlark rule definition. message RuleInfo { - // The name of the rule. + // The name under which the rule is made accessible to a user of this module, + // including any structs it is nested in, for example "foo.foo_library". string rule_name = 1; // The documentation string of the rule. @@ -71,11 +81,22 @@ message RuleInfo { // The attributes of the rule. repeated AttributeInfo attribute = 3; + + // The module where and the name under which the rule was originally declared. + // + // Note: legacy Stardoc (0.5.x and earlier) does not set this field. + OriginKey origin_key = 4; + + // The list of providers that the rule's implementation must return. Unset if + // the rule lists no advertised providers. + // + // Note: legacy Stardoc (0.5.x and earlier) does not set this field. + ProviderNameGroup advertised_providers = 5; } -// Representation of a Starlark rule attribute definition, comprised of an -// attribute name, and a schema defined by a call to one of the 'attr' module -// methods enumerated at +// Representation of a Starlark rule, repository rule, or module extension tag +// attribute definition, comprised of an attribute name, and a schema defined by +// a call to one of the 'attr' module methods enumerated at // https://bazel.build/rules/lib/attr message AttributeInfo { // The name of the attribute. @@ -95,26 +116,46 @@ message AttributeInfo { // The target(s) in this attribute must define all the providers of at least // one of the ProviderNameGroups in this list. If the Attribute Type is not a // label, a label list, or a label-keyed string dictionary, the field will be - // left empty. + // left empty. For attributes of a repository rule or a module extension tag, + // this attribute is meaningless and may be ignored. + // TODO(b/290788853): ensure this field is always empty for attributes of a + // repository rule or a module extension tag. repeated ProviderNameGroup provider_name_group = 5; // The string representation of the default value of this attribute. string default_value = 6; } -// Representation of a set of providers that a rule attribute may be required to -// have. +// Representation of a set of providers. message ProviderNameGroup { - // The names of the providers that must be given by any dependency appearing - // in this attribute. The name will be "Unknown Provider" if the name is - // unidentifiable, for example, if the provider is part of a namespace. - // TODO(kendalllane): Fix documentation of providers from namespaces. + // The names of the providers. + // + // This field is only intended for rendering human-readable output. + // Please use origin_key (a list of the same length and in the same order as + // this field) for cross-references and tooling. + // + // Note: legacy Stardoc (0.5.x and earlier) is unable to extract the name in + // some circumstances (for example, if the provider is nested in a struct), + // and in that case, the provider name will be "Unknown Provider". repeated string provider_name = 1; + + // A list of unambiguous references to providers, of the same length and in + // the same order as the provider_name list. + // + // For provider symbols, this means modules where and the names under which + // the providers were originally declared. + // + // For legacy struct providers, origin_key.file is unset. + // + // Note: legacy Stardoc (0.5.x and earlier) does not set this field. + repeated OriginKey origin_key = 2; } // Representation of Starlark function definition. message StarlarkFunctionInfo { - // The name of the function. + // The name under which the function is made accessible to a user of this + // module, including any structs it is nested in, for example + // "foo.frobnicate". string function_name = 1; // The parameters for the function. @@ -129,6 +170,12 @@ message StarlarkFunctionInfo { // The deprecation for the function. FunctionDeprecationInfo deprecated = 5; + + // The module where and the name under which the function was originally + // declared. + // + // Note: legacy Stardoc (0.5.x and earlier) does not set this field. + OriginKey origin_key = 6; } // Representation of a Starlark function parameter definition. @@ -174,7 +221,8 @@ message ProviderFieldInfo { // Representation of a Starlark provider definition. message ProviderInfo { - // The name of the provider. + // The name under which the provider is made accessible to a user of this + // module, including any structs it is nested in, for example "foo.FooInfo". string provider_name = 1; // The description of the provider. @@ -182,11 +230,19 @@ message ProviderInfo { // The fields of the provider. repeated ProviderFieldInfo field_info = 3; + + // The module where and the name under which the provider was originally + // declared. + // + // Note: legacy Stardoc (0.5.x and earlier) does not set this field. + OriginKey origin_key = 4; } // Representation of a Starlark aspect definition. message AspectInfo { - // The name of the aspect. + // The name under which the aspect is made accessible to a user of this + // module, including any structs it is nested in, for example + // "foo.foo_aspect". string aspect_name = 1; // The documentation string of the aspect. @@ -197,4 +253,85 @@ message AspectInfo { // The attributes of the aspect. repeated AttributeInfo attribute = 4; + + // The module where and the name under which the aspect was originally + // declared. + // + // Note: legacy Stardoc (0.5.x and earlier) does not set this field. + OriginKey origin_key = 5; +} + +// Representation of a Bazel module extension, i.e. the object returned by +// calling `module_extension(...)`. +// +// Note: legacy Stardoc (0.5.x and earlier) does not emit this message. +message ModuleExtensionInfo { + // The name under which the extension is made accessible to a user of this + // Starlark module. + string extension_name = 1; + + // The documentation string of the extension. + string doc_string = 2; + + // The tag classes of the extension. + repeated ModuleExtensionTagClassInfo tag_class = 3; + + // The Starlark module where the Bazel module extension was originally + // declared; origin_key.name is currently never set. + // TODO(arostovtsev): attempt to retrieve the name under which the module + // extension was originally declared if it was declared as a global. + OriginKey origin_key = 4; +} + +// Representation of a Bazel module extension tag class. +message ModuleExtensionTagClassInfo { + // The name of the tag for this tag class. + string tag_name = 1; + + // The documentation string of the tag class. + string doc_string = 2; + + // The tag class's attributes. + repeated AttributeInfo attribute = 3; +} + +// Representation of a Bazel repository rule, i.e. the object returned by +// calling `repository_rule(...)`. +// +// Note: legacy Stardoc (0.5.x and earlier) does not emit this message, instead +// using RuleInfo. +message RepositoryRuleInfo { + // The name under which the repository rule is made accessible to a user of + // this Starlark module. + string rule_name = 1; + + // The documentation string of the repository rule. + string doc_string = 2; + + // The attributes of the repository rule. + repeated AttributeInfo attribute = 3; + + // Environment variables that this repository rule depends on. + repeated string environ = 4; + + // The Starlark module where and the name under which the repository rule was + // originally declared. + OriginKey origin_key = 5; +} + +// Representation of the origin of a rule, provider, aspect, or function. +// Intended to be used for building unambiguous cross-references: for example, +// between an element of a ProviderNameGroup required by a rule attribute and +// its corresponding ProviderInfo. +message OriginKey { + // The name under which the entity was originally exported. Unset when the + // entity was not exported in its module. + string name = 1; + + // The display form of the label of the module file in which the entity was + // originally declared (as seen from the starlark_doc_extract or Stardoc + // target's repo), or "" for Bazel's built-in entities implemented in + // Java. Unset when there is no module file (such as for legacy struct + // providers, when the module is a REPL, or in Bazel's internal tests). + string file = 2; } diff --git a/stardoc/renderer_binary.jar b/stardoc/renderer_binary.jar index a2f8897f..c1a31240 100755 Binary files a/stardoc/renderer_binary.jar and b/stardoc/renderer_binary.jar differ diff --git a/stardoc/stardoc_binary.jar b/stardoc/stardoc_binary.jar index f10aece8..2e8860a0 100755 Binary files a/stardoc/stardoc_binary.jar and b/stardoc/stardoc_binary.jar differ diff --git a/stardoc/templates/markdown_tables/aspect.vm b/stardoc/templates/markdown_tables/aspect.vm index 14bc66d3..36aa47a0 100644 --- a/stardoc/templates/markdown_tables/aspect.vm +++ b/stardoc/templates/markdown_tables/aspect.vm @@ -27,6 +27,6 @@ $aspectInfo.getDocString() | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | #foreach ($attribute in $aspectInfo.getAttributeList()) -| $attribute.name | #if(!$attribute.docString.isEmpty()) ${util.markdownCellFormat($attribute.docString)} #else - #end | ${util.attributeTypeString($attribute)} | ${util.mandatoryString($attribute)} | #if(!$attribute.defaultValue.isEmpty()) `$attribute.defaultValue` #end | +| $attribute.name | #if(!$attribute.docString.isEmpty()) ${util.markdownCellFormat($attribute.docString)} #else - #end | ${util.attributeTypeString($attribute)} | ${util.mandatoryString($attribute)} | #if(!$attribute.defaultValue.isEmpty()) ${util.markdownCodeSpan($attribute.defaultValue)} #end | #end #end diff --git a/stardoc/templates/markdown_tables/func.vm b/stardoc/templates/markdown_tables/func.vm index 3f7d3dba..e53b81a9 100644 --- a/stardoc/templates/markdown_tables/func.vm +++ b/stardoc/templates/markdown_tables/func.vm @@ -15,7 +15,7 @@ ${funcInfo.docString} | Name | Description | Default Value | | :------------- | :------------- | :------------- | #foreach ($param in $funcInfo.getParameterList()) -| $param.name | #if(!$param.docString.isEmpty()) ${util.markdownCellFormat($param.docString)} #else

-

#end | #if(!$param.getDefaultValue().isEmpty()) `$param.getDefaultValue()` #else none #end| +| $param.name | #if(!$param.docString.isEmpty()) ${util.markdownCellFormat($param.docString)} #else

-

#end | #if(!$param.getDefaultValue().isEmpty()) ${util.markdownCodeSpan($param.defaultValue)} #else none #end| #end #end #if (!$funcInfo.getReturn().docString.isEmpty()) diff --git a/stardoc/templates/markdown_tables/rule.vm b/stardoc/templates/markdown_tables/rule.vm index 519a6f93..0b73239c 100644 --- a/stardoc/templates/markdown_tables/rule.vm +++ b/stardoc/templates/markdown_tables/rule.vm @@ -15,6 +15,6 @@ ${ruleInfo.docString} | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | #foreach ($attribute in $ruleInfo.getAttributeList()) -| $attribute.name | #if(!$attribute.docString.isEmpty()) ${util.markdownCellFormat($attribute.docString)} #else - #end | ${util.attributeTypeString($attribute)} | ${util.mandatoryString($attribute)} | #if(!$attribute.defaultValue.isEmpty()) `$attribute.defaultValue` #end | +| $attribute.name | #if(!$attribute.docString.isEmpty()) ${util.markdownCellFormat($attribute.docString)} #else - #end | ${util.attributeTypeString($attribute)} | ${util.mandatoryString($attribute)} | #if(!$attribute.defaultValue.isEmpty()) ${util.markdownCodeSpan($attribute.defaultValue)} #end | #end #end diff --git a/test/testdata/angle_bracket_test/golden.md b/test/testdata/angle_bracket_test/golden.md index e43319d9..a9ccc142 100755 --- a/test/testdata/angle_bracket_test/golden.md +++ b/test/testdata/angle_bracket_test/golden.md @@ -79,7 +79,7 @@ foo = "" | Name | Description | Default Value | | :------------- | :------------- | :------------- | | param | an arg with **formatted** docstring, <default> by default. | `""` | -| md_string | A markdown string. | `"foo `1<<10` bar"` | +| md_string | A markdown string. | ``"foo `1<<10` bar"`` | **RETURNS** diff --git a/test/testdata/misc_apis_test/golden.md b/test/testdata/misc_apis_test/golden.md index b223ff51..1a6b8675 100755 --- a/test/testdata/misc_apis_test/golden.md +++ b/test/testdata/misc_apis_test/golden.md @@ -7,7 +7,7 @@ ## my_rule 
-my_rule(name, deps, extra_arguments, out, src, tool)
+my_rule(name, deps, src, out, extra_arguments, tool)
This rule exercises some of the build API. @@ -19,9 +19,9 @@ This rule exercises some of the build API. | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | | deps | A list of dependencies. | List of labels | optional | `[]` | -| extra_arguments | - | List of strings | optional | `[]` | -| out | The output file. | Label | required | | | src | The source file. | Label | optional | `None` | +| out | The output file. | Label | required | | +| extra_arguments | - | List of strings | optional | `[]` | | tool | The location of the tool to use. | Label | optional | `//foo/bar/baz:target` | diff --git a/test/testdata/multi_level_namespace_test/golden.md b/test/testdata/multi_level_namespace_test/golden.md index 85791c9a..3e753c08 100755 --- a/test/testdata/multi_level_namespace_test/golden.md +++ b/test/testdata/multi_level_namespace_test/golden.md @@ -2,12 +2,24 @@ A test that verifies documenting a multi-leveled namespace of functions. - + -## my_namespace.min +## my_namespace.foo.bar.baz 
-my_namespace.min(integers)
+my_namespace.foo.bar.baz()
+
+ +This function does nothing. + + + + + +## my_namespace.math.min + +
+my_namespace.math.min(integers)
Returns the minimum of given elements. @@ -17,19 +29,19 @@ Returns the minimum of given elements. | Name | Description | Default Value | | :------------- | :------------- | :------------- | -| integers | A list of integers. Must not be empty. | none | +| integers | A list of integers. Must not be empty. | none | **RETURNS** The minimum integer in the given list. - + -## my_namespace.math.min +## my_namespace.min 
-my_namespace.math.min(integers)
+my_namespace.min(integers)
Returns the minimum of given elements. @@ -39,19 +51,19 @@ Returns the minimum of given elements. | Name | Description | Default Value | | :------------- | :------------- | :------------- | -| integers | A list of integers. Must not be empty. | none | +| integers | A list of integers. Must not be empty. | none | **RETURNS** The minimum integer in the given list. - + -## my_namespace.foo.bar.baz +## my_namespace.one.three.does_nothing 
-my_namespace.foo.bar.baz()
+my_namespace.one.three.does_nothing()
This function does nothing. @@ -80,15 +92,3 @@ Returns the minimum of given elements. The minimum integer in the given list. - - -## my_namespace.one.three.does_nothing - -
-my_namespace.one.three.does_nothing()
-
- -This function does nothing. - - - diff --git a/test/testdata/multi_level_namespace_test_with_whitelist/golden.md b/test/testdata/multi_level_namespace_test_with_whitelist/golden.md index 1ca16086..8e29b896 100644 --- a/test/testdata/multi_level_namespace_test_with_whitelist/golden.md +++ b/test/testdata/multi_level_namespace_test_with_whitelist/golden.md @@ -4,12 +4,12 @@ A test that verifies documenting a multi-leveled namespace of functions with whi The whitelist symbols should cause everything in my_namespace to to be documented, but only a specific symbol in other_namespace to be documented. - + -## my_namespace.min +## my_namespace.math.min 
-my_namespace.min(integers)
+my_namespace.math.min(integers)
Returns the minimum of given elements. @@ -19,15 +19,15 @@ Returns the minimum of given elements. | Name | Description | Default Value | | :------------- | :------------- | :------------- | -| integers |

-

| none | +| integers |

-

| none | - + -## my_namespace.math.min +## my_namespace.min 
-my_namespace.math.min(integers)
+my_namespace.min(integers)
Returns the minimum of given elements. @@ -37,7 +37,7 @@ Returns the minimum of given elements. | Name | Description | Default Value | | :------------- | :------------- | :------------- | -| integers |

-

| none | +| integers |

-

| none | diff --git a/test/testdata/namespace_test/golden.md b/test/testdata/namespace_test/golden.md index 83e9c558..6e4c453d 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. | other_list | The second list | none | - + -## my_namespace.min +## my_namespace.join_strings 
-my_namespace.min(integers)
+my_namespace.join_strings(strings, delimiter)
-Returns the minimum of given elements. +Joins the given strings with a delimiter. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | -| integers | A list of integers. Must not be empty. | none | +| strings | A list of strings to join. | none | +| delimiter | The delimiter to use | `", "` | **RETURNS** -The minimum integer in the given list. +The joined string. - + -## my_namespace.join_strings +## my_namespace.min 
-my_namespace.join_strings(strings, delimiter)
+my_namespace.min(integers)
-Joins the given strings with a delimiter. +Returns the minimum of given elements. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | -| strings | A list of strings to join. | none | -| delimiter | The delimiter to use | `", "` | +| integers | A list of integers. Must not be empty. | none | **RETURNS** -The joined string. +The minimum integer in the given list. diff --git a/test/testdata/proto_format_test/golden.raw b/test/testdata/proto_format_test/golden.raw index a93d367e..d158834b 100644 Binary files a/test/testdata/proto_format_test/golden.raw and b/test/testdata/proto_format_test/golden.raw differ