diff options
author | allevato <allevato@google.com> | 2017-07-07 21:40:50 +0200 |
---|---|---|
committer | László Csomor <laszlocsomor@google.com> | 2017-07-10 09:16:35 +0200 |
commit | 45b79e51575d93d4c1da93e070b159842a73b56a (patch) | |
tree | 1f4a0184910de731e46786f85a580e92628d999c /src/main/java/com/google/devtools/build/lib/rules | |
parent | 8ff3d2d61d1638553ef1315ca0f52a8357feca2f (diff) |
Add doc argument to attr.*, rule, aspect, and provider.
Skydoc can use these arguments to obtain documentation instead of (or in
addition to) Python-style docstrings.
RELNOTES: None.
PiperOrigin-RevId: 161233014
Diffstat (limited to 'src/main/java/com/google/devtools/build/lib/rules')
-rw-r--r-- | src/main/java/com/google/devtools/build/lib/rules/SkylarkAttr.java | 126 | ||||
-rw-r--r-- | src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleClassFunctions.java | 25 |
2 files changed, 146 insertions, 5 deletions
diff --git a/src/main/java/com/google/devtools/build/lib/rules/SkylarkAttr.java b/src/main/java/com/google/devtools/build/lib/rules/SkylarkAttr.java index a6609d4666..6793119eaf 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/SkylarkAttr.java +++ b/src/main/java/com/google/devtools/build/lib/rules/SkylarkAttr.java @@ -87,7 +87,7 @@ public final class SkylarkAttr implements SkylarkValue { private static final String ALLOW_RULES_ARG = "allow_rules"; private static final String ALLOW_RULES_DOC = "which rule targets (name of the classes) are allowed. This is deprecated (kept only for " - + "compatiblity), use providers instead."; + + "compatibility), use providers instead."; private static final String ASPECTS_ARG = "aspects"; private static final String ASPECTS_ARG_DOC = @@ -102,6 +102,10 @@ public final class SkylarkAttr implements SkylarkValue { private static final String DEFAULT_ARG = "default"; private static final String DEFAULT_DOC = "the default value of the attribute."; + private static final String DOC_ARG = "doc"; + private static final String DOC_DOC = + "a description of the attribute that can be extracted by documentation generating tools."; + private static final String EXECUTABLE_ARG = "executable"; private static final String EXECUTABLE_DOC = "True if the labels have to be executable. This means the label must refer to an " @@ -462,6 +466,14 @@ public final class SkylarkAttr implements SkylarkValue { positional = false ), @Param( + name = DOC_ARG, + type = String.class, + defaultValue = "''", + doc = DOC_DOC, + named = true, + positional = false + ), + @Param( name = MANDATORY_ARG, type = Boolean.class, defaultValue = "False", @@ -486,6 +498,7 @@ public final class SkylarkAttr implements SkylarkValue { new BuiltinFunction("int") { public Descriptor invoke( Integer defaultInt, + String doc, Boolean mandatory, SkylarkList<?> values, FuncallExpression ast, @@ -518,6 +531,14 @@ public final class SkylarkAttr implements SkylarkValue { positional = false ), @Param( + name = DOC_ARG, + type = String.class, + defaultValue = "''", + doc = DOC_DOC, + named = true, + positional = false + ), + @Param( name = MANDATORY_ARG, type = Boolean.class, defaultValue = "False", @@ -542,6 +563,7 @@ public final class SkylarkAttr implements SkylarkValue { new BuiltinFunction("string") { public Descriptor invoke( String defaultString, + String doc, Boolean mandatory, SkylarkList<?> values, FuncallExpression ast, @@ -587,6 +609,14 @@ public final class SkylarkAttr implements SkylarkValue { + "<code>attr.label(default = \"//a:b\")</code>" ), @Param( + name = DOC_ARG, + type = String.class, + defaultValue = "''", + doc = DOC_DOC, + named = true, + positional = false + ), + @Param( name = EXECUTABLE_ARG, type = Boolean.class, defaultValue = "False", @@ -674,6 +704,7 @@ public final class SkylarkAttr implements SkylarkValue { new BuiltinFunction("label") { public Descriptor invoke( Object defaultO, + String doc, Boolean executable, Object allowFiles, Object allowSingleFile, @@ -739,6 +770,14 @@ public final class SkylarkAttr implements SkylarkValue { doc = DEFAULT_DOC ), @Param( + name = DOC_ARG, + type = String.class, + defaultValue = "''", + doc = DOC_DOC, + named = true, + positional = false + ), + @Param( name = MANDATORY_ARG, type = Boolean.class, defaultValue = "False", @@ -764,6 +803,7 @@ public final class SkylarkAttr implements SkylarkValue { new BuiltinFunction("string_list") { public Descriptor invoke( SkylarkList<?> defaultList, + String doc, Boolean mandatory, Boolean nonEmpty, Boolean allowEmpty, @@ -803,6 +843,14 @@ public final class SkylarkAttr implements SkylarkValue { doc = DEFAULT_DOC ), @Param( + name = DOC_ARG, + type = String.class, + defaultValue = "''", + doc = DOC_DOC, + named = true, + positional = false + ), + @Param( name = MANDATORY_ARG, type = Boolean.class, defaultValue = "False", @@ -828,6 +876,7 @@ public final class SkylarkAttr implements SkylarkValue { new BuiltinFunction("int_list") { public Descriptor invoke( SkylarkList<?> defaultList, + String doc, Boolean mandatory, Boolean nonEmpty, Boolean allowEmpty, @@ -877,6 +926,14 @@ public final class SkylarkAttr implements SkylarkValue { + "<code>attr.label_list(default = [\"//a:b\", \"//a:c\"])</code>" ), @Param( + name = DOC_ARG, + type = String.class, + defaultValue = "''", + doc = DOC_DOC, + named = true, + positional = false + ), + @Param( name = ALLOW_FILES_ARG, // bool or FileType filter defaultValue = "None", named = true, @@ -958,6 +1015,7 @@ public final class SkylarkAttr implements SkylarkValue { new BuiltinFunction("label_list") { public Descriptor invoke( Object defaultList, + String doc, Object allowFiles, Object allowRules, SkylarkList<?> providers, @@ -1029,6 +1087,14 @@ public final class SkylarkAttr implements SkylarkValue { + "{\"//a:b\": \"value\", \"//a:c\": \"string\"})</code>" ), @Param( + name = DOC_ARG, + type = String.class, + defaultValue = "''", + doc = DOC_DOC, + named = true, + positional = false + ), + @Param( name = ALLOW_FILES_ARG, // bool or FileType filter defaultValue = "None", named = true, @@ -1110,6 +1176,7 @@ public final class SkylarkAttr implements SkylarkValue { new BuiltinFunction("label_keyed_string_dict") { public Descriptor invoke( Object defaultList, + String doc, Object allowFiles, Object allowRules, SkylarkList<?> providers, @@ -1172,6 +1239,14 @@ public final class SkylarkAttr implements SkylarkValue { doc = DEFAULT_DOC ), @Param( + name = DOC_ARG, + type = String.class, + defaultValue = "''", + doc = DOC_DOC, + named = true, + positional = false + ), + @Param( name = MANDATORY_ARG, type = Boolean.class, defaultValue = "False", @@ -1186,7 +1261,7 @@ public final class SkylarkAttr implements SkylarkValue { private static BuiltinFunction bool = new BuiltinFunction("bool") { public Descriptor invoke( - Boolean defaultO, Boolean mandatory, FuncallExpression ast, Environment env) + Boolean defaultO, String doc, Boolean mandatory, FuncallExpression ast, Environment env) throws EvalException { env.checkLoadingOrWorkspacePhase("attr.bool", ast.getLocation()); return createAttrDescriptor( @@ -1218,6 +1293,14 @@ public final class SkylarkAttr implements SkylarkValue { doc = DEFAULT_DOC ), @Param( + name = DOC_ARG, + type = String.class, + defaultValue = "''", + doc = DOC_DOC, + named = true, + positional = false + ), + @Param( name = MANDATORY_ARG, type = Boolean.class, defaultValue = "False", @@ -1232,7 +1315,7 @@ public final class SkylarkAttr implements SkylarkValue { private static BuiltinFunction output = new BuiltinFunction("output") { public Descriptor invoke( - Object defaultO, Boolean mandatory, FuncallExpression ast, Environment env) + Object defaultO, String doc, Boolean mandatory, FuncallExpression ast, Environment env) throws EvalException { env.checkLoadingOrWorkspacePhase("attr.output", ast.getLocation()); return createNonconfigurableAttrDescriptor( @@ -1263,6 +1346,14 @@ public final class SkylarkAttr implements SkylarkValue { doc = DEFAULT_DOC ), @Param( + name = DOC_ARG, + type = String.class, + defaultValue = "''", + doc = DOC_DOC, + named = true, + positional = false + ), + @Param( name = MANDATORY_ARG, type = Boolean.class, defaultValue = "False", @@ -1292,6 +1383,7 @@ public final class SkylarkAttr implements SkylarkValue { new BuiltinFunction("output_list") { public Descriptor invoke( SkylarkList defaultList, + String doc, Boolean mandatory, Boolean nonEmpty, Boolean allowEmpty, @@ -1334,6 +1426,14 @@ public final class SkylarkAttr implements SkylarkValue { doc = DEFAULT_DOC ), @Param( + name = DOC_ARG, + type = String.class, + defaultValue = "''", + doc = DOC_DOC, + named = true, + positional = false + ), + @Param( name = MANDATORY_ARG, type = Boolean.class, named = true, @@ -1363,6 +1463,7 @@ public final class SkylarkAttr implements SkylarkValue { new BuiltinFunction("string_dict") { public Descriptor invoke( SkylarkDict<?, ?> defaultO, + String doc, Boolean mandatory, Boolean nonEmpty, Boolean allowEmpty, @@ -1406,6 +1507,14 @@ public final class SkylarkAttr implements SkylarkValue { doc = DEFAULT_DOC ), @Param( + name = DOC_ARG, + type = String.class, + defaultValue = "''", + doc = DOC_DOC, + named = true, + positional = false + ), + @Param( name = MANDATORY_ARG, type = Boolean.class, defaultValue = "False", @@ -1435,6 +1544,7 @@ public final class SkylarkAttr implements SkylarkValue { new BuiltinFunction("string_list_dict") { public Descriptor invoke( SkylarkDict<?, ?> defaultO, + String doc, Boolean mandatory, Boolean nonEmpty, Boolean allowEmpty, @@ -1477,6 +1587,14 @@ public final class SkylarkAttr implements SkylarkValue { doc = DEFAULT_DOC ), @Param( + name = DOC_ARG, + type = String.class, + defaultValue = "''", + doc = DOC_DOC, + named = true, + positional = false + ), + @Param( name = MANDATORY_ARG, type = Boolean.class, defaultValue = "False", @@ -1491,7 +1609,7 @@ public final class SkylarkAttr implements SkylarkValue { private static BuiltinFunction license = new BuiltinFunction("license") { public Descriptor invoke( - Object defaultO, Boolean mandatory, FuncallExpression ast, Environment env) + Object defaultO, String doc, Boolean mandatory, FuncallExpression ast, Environment env) throws EvalException { env.checkLoadingOrWorkspacePhase("attr.license", ast.getLocation()); return createNonconfigurableAttrDescriptor( diff --git a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleClassFunctions.java b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleClassFunctions.java index ecc46a4268..a2cfcb29a7 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleClassFunctions.java +++ b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleClassFunctions.java @@ -258,11 +258,20 @@ public class SkylarkRuleClassFunctions { + "<pre class=\"language-python\">data = provider()\n" + "d = data(x = 2, y = 3)\n" + "print(d.x + d.y) # prints 5</pre>", + parameters = { + @Param( + name = "doc", + type = String.class, + defaultValue = "''", + doc = + "A description of the provider that can be extracted by documentation generating tools." + ) + }, useLocation = true ) private static final BuiltinFunction provider = new BuiltinFunction("provider") { - public ClassObjectConstructor invoke(Location location) { + public ClassObjectConstructor invoke(String doc, Location location) { return new SkylarkClassObjectConstructor( "<no name>", // name is set on export. location); @@ -391,6 +400,12 @@ public class SkylarkRuleClassFunctions { + "If set, the set of toolchains this rule requires. Toolchains will be " + "found by checking the current platform, and provided to the rule " + "implementation via <code>ctx.toolchain</code>." + ), + @Param( + name = "doc", + type = String.class, + defaultValue = "''", + doc = "A description of the rule that can be extracted by documentation generating tools." ) }, useAst = true, @@ -411,6 +426,7 @@ public class SkylarkRuleClassFunctions { SkylarkList hostFragments, Boolean skylarkTestable, SkylarkList<String> toolchains, + String doc, FuncallExpression ast, Environment funcallEnv) throws EvalException, ConversionException { @@ -605,6 +621,12 @@ public class SkylarkRuleClassFunctions { + "If set, the set of toolchains this rule requires. Toolchains will be " + "found by checking the current platform, and provided to the rule " + "implementation via <code>ctx.toolchain</code>." + ), + @Param( + name = "doc", + type = String.class, + defaultValue = "''", + doc = "A description of the aspect that can be extracted by documentation generating tools." ) }, useEnvironment = true, @@ -621,6 +643,7 @@ public class SkylarkRuleClassFunctions { SkylarkList fragments, SkylarkList hostFragments, SkylarkList<String> toolchains, + String doc, FuncallExpression ast, Environment funcallEnv) throws EvalException { |