diff --git a/WORKSPACE b/WORKSPACE index 2191a2c2..4cab2e20 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 = "7316ec4d1a3a90f2ae62ad552fd0fd63e195b46a", # Temporary commit in a fork of Bazel. + 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..f2abf860 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,11 @@ 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; } // Representation of a Starlark rule attribute type. These generally @@ -63,7 +68,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,6 +77,17 @@ 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 @@ -102,19 +119,36 @@ message AttributeInfo { 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 +163,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 +214,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 +223,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 +246,27 @@ 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 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..bba6dbcf 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..983f4280 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..a3a2816d 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.markdownInlineCodeEscape($attribute.defaultValue)}` #end | #end #end diff --git a/stardoc/templates/markdown_tables/func.vm b/stardoc/templates/markdown_tables/func.vm index 3f7d3dba..50b3eb78 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.markdownInlineCodeEscape($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..dea44394 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.markdownInlineCodeEscape($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..8184115e 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/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