1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
|
// 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. A single invocation of Stardoc 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;
}
// 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 of the rule.
string rule_name = 1;
// The documentation string of the rule.
string doc_string = 2;
// The attributes of the rule.
repeated AttributeInfo attribute = 3;
}
// 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
// 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.
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.
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.
repeated string provider_name = 1;
}
// Representation of Starlark function definition.
message StarlarkFunctionInfo {
// The name of the function.
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;
}
// 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 of the provider.
string provider_name = 1;
// The description of the provider.
string doc_string = 2;
// The fields of the provider.
repeated ProviderFieldInfo field_info = 3;
}
// Representation of a Starlark aspect definition.
message AspectInfo {
// The name of the 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;
}
|
