blob: c883aec03c51e45af8c53d200b2247a9d9e5506e [file] [log] [blame]
// Copyright 2019 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.
//
// Protos for Stardoc data.
//
// Stardoc collects information about Starlark functions, providers, and rules.
syntax = "proto3";
package stardoc_output;
// option java_api_version = 2;
option java_package = "com.google.devtools.build.skydoc.rendering.proto";
option java_outer_classname = "StardocOutputProtos";
// 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;
repeated ProviderInfo provider_info = 2;
repeated StarlarkFunctionInfo func_info = 3;
repeated AspectInfo aspect_info = 4;
// 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;
repeated MacroInfo macro_info = 9;
}
// Representation of a Starlark rule attribute type. These generally
// have a one-to-one correspondence with functions defined at
// https://bazel.build/rules/lib/attr.
enum AttributeType {
UNKNOWN = 0;
// A special case of STRING; all rules have exactly one implicit
// attribute "name" of type NAME.
NAME = 1;
INT = 2;
LABEL = 3;
STRING = 4;
STRING_LIST = 5;
INT_LIST = 6;
LABEL_LIST = 7;
BOOLEAN = 8;
LABEL_STRING_DICT = 9;
STRING_DICT = 10;
STRING_LIST_DICT = 11;
OUTPUT = 12;
OUTPUT_LIST = 13;
}
// Representation of a Starlark rule definition.
message RuleInfo {
// 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.
string doc_string = 2;
// The attributes of the rule.
repeated AttributeInfo attribute = 3;
// Note: legacy Stardoc (0.5.x and earlier) does not set any fields below.
// The module where and the name under which the rule was originally declared.
OriginKey origin_key = 4;
// The list of providers that the rule's implementation must return. Unset if
// the rule lists no advertised providers.
ProviderNameGroup advertised_providers = 5;
// True if this is a test rule.
bool test = 6;
// True if this is an executable rule.
//
// Note: if test is true, executable is also true (test rules are implicitly
// executable).
bool executable = 7;
}
// Representation of a Starlark symbolic macro definition.
// Note: symbolic macros (and thus, their documentation format) are an
// experimental feature gated by the --experimental_enable_first_class_macros
// flag.
message MacroInfo {
// The name under which the macro is made accessible to a user of this module,
// including any structs it is nested in, for example "foo.foo_library".
string macro_name = 1;
// The documentation string of the macro.
string doc_string = 2;
// The attributes of the macro.
repeated AttributeInfo attribute = 3;
// The module where and the name under which the macro was originally
// declared.
OriginKey origin_key = 4;
}
// 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.
string name = 1;
// The documentation string of the attribute, supplied via the 'doc'
// parameter to the schema-creation call.
string doc_string = 2;
// The type of the attribute, defined generally by which function is invoked
// in the attr module.
AttributeType type = 3;
// If true, all targets of the rule must specify a value for this attribute.
bool mandatory = 4;
// 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. 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;
// If true, the attribute is non-configurable.
bool nonconfigurable = 7;
}
// Representation of a set of providers.
message ProviderNameGroup {
// 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 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.
repeated FunctionParamInfo parameter = 2;
// The documented description of the function (if specified in the function's
// docstring).
string doc_string = 3;
// The return value for the function.
FunctionReturnInfo return = 4;
// 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.
message FunctionParamInfo {
// The name of the parameter.
string name = 1;
// The documented description of the parameter (if specified in the function's
// docstring).
string doc_string = 2;
// If not an empty string, the default value of the parameter displayed
// as a string.
string default_value = 3;
// If true, the default value is unset and a value is needed for this
// parameter. This might be false even if defaultValue is empty in the case of
// special parameter such as *args and **kwargs"
bool mandatory = 4;
}
message FunctionReturnInfo {
// The documented return value of the function (if specified in the function's
// docstring).
string doc_string = 1;
}
message FunctionDeprecationInfo {
// The documented deprecation of the function (if specified in the function's
// docstring).
string doc_string = 1;
}
// Representation of a Starlark provider field definition, comprised of
// the field name and provider description.
message ProviderFieldInfo {
// The name of the field.
string name = 1;
// The description of the provider.
string doc_string = 2;
}
// Representation of a Starlark provider definition.
message ProviderInfo {
// 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.
string doc_string = 2;
// The fields of the provider.
repeated ProviderFieldInfo field_info = 3;
// Note: legacy Stardoc (0.5.x and earlier) does not set any fields below.
// The module where and the name under which the provider was originally
// declared.
OriginKey origin_key = 4;
// The provider's init callback.
StarlarkFunctionInfo init = 5;
}
// Representation of a Starlark aspect definition.
message AspectInfo {
// 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.
string doc_string = 2;
// The rule attributes along which the aspect propagates.
repeated string aspect_attribute = 3;
// 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 "<native>" 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;
}