diff options
Diffstat (limited to 'src/main/java/com/google/devtools/build/lib')
-rw-r--r-- | src/main/java/com/google/devtools/build/lib/packages/ClassObjectConstructor.java | 36 | ||||
-rw-r--r-- | src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleClassFunctions.java | 26 |
2 files changed, 41 insertions, 21 deletions
diff --git a/src/main/java/com/google/devtools/build/lib/packages/ClassObjectConstructor.java b/src/main/java/com/google/devtools/build/lib/packages/ClassObjectConstructor.java index e2e0ccf7b0..8275e6a69d 100644 --- a/src/main/java/com/google/devtools/build/lib/packages/ClassObjectConstructor.java +++ b/src/main/java/com/google/devtools/build/lib/packages/ClassObjectConstructor.java @@ -27,19 +27,37 @@ import javax.annotation.Nullable; /** * Declared Provider (a constructor for {@link SkylarkClassObject}). * - * Declared providers can be declared either natively ({@link NativeClassObjectConstructor} - * or in Skylark {@link SkylarkClassObjectConstructor}. + * <p>Declared providers can be declared either natively ({@link NativeClassObjectConstructor} or in + * Skylark {@link SkylarkClassObjectConstructor}. * - * {@link ClassObjectConstructor} serves both as "type identifier" for declared provider + * <p>{@link ClassObjectConstructor} serves both as "type identifier" for declared provider * instances and as a function that can be called to construct a provider. * - * Prefer to use {@link Key} as a serializable identifier of {@link ClassObjectConstructor}. - * In particular, {@link Key} should be used in all data structures exposed to Skyframe. + * <p>Prefer to use {@link Key} as a serializable identifier of {@link ClassObjectConstructor}. In + * particular, {@link Key} should be used in all data structures exposed to Skyframe. */ -@SkylarkModule(name = "provider", - doc = "A constructor for simple value objects. " - + "See the global <a href=\"globals.html#provider\">provider</a> function " - + "for more details." +@SkylarkModule( + name = "Provider", + doc = + "A constructor for simple value objects, known as provider instances." + + "<br>" + + "This value has a dual purpose:" + + " <ul>" + + " <li>It is a function that can be called to construct 'struct'-like values:" + + "<pre class=\"language-python\">DataInfo = provider()\n" + + "d = DataInfo(x = 2, y = 3)\n" + + "print(d.x + d.y) # prints 5</pre>" + + " <i>Some providers, defined internally, do not allow instance creation</i>" + + " </li>" + + " <li>It is a <i>key</i> to access a provider instance on a" + + " <a href=\"lib/Target.html\">Target</a>" + + "<pre class=\"language-python\">DataInfo = provider()\n" + + "def _rule_impl(ctx)\n" + + " ... ctx.attr.dep[DataInfo]</pre>" + + " </li>" + + " </ul>" + + "Create a new <code>Provider</code> using the " + + "<a href=\"globals.html#provider\">provider</a> function." ) @Immutable public abstract class ClassObjectConstructor extends BaseFunction { 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 24803c108a..aefdfaf3c9 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 @@ -194,16 +194,18 @@ public class SkylarkRuleClassFunctions { @SkylarkSignature( name = "DefaultInfo", returnType = ClassObjectConstructor.class, - doc = "A provider that is provided by every rule, even if it iss not returned explicitly. " - + "A <code>DefaultInfo</code> accepts all special parameters that can be returned " - + "from rule implementation function in a struct, which are <code>runfiles</code>, " - + "<code>data_runfiles</code>, <code>default_runfiles</code>, " - + "<code>output_groups</code>, <code>instrumented_files</code>, and all " - + "<a href=\"skylark-provider.html\">providers</a> that are available on built-in rules. " - + "Each instance of the default provider contains the following standard fields: " - + "<code>data_runfiles</code>, <code>default_runfiles</code>, <code>files</code>, " - + "and <code>files_to_run</code>. The values of these fields are equivalent to the " - + "values of the corresponding fields of the target the default provider belongs to." + doc = + "A provider that is provided by every rule, even if it iss not returned explicitly. " + + "A <code>DefaultInfo</code> accepts all special parameters that can be returned " + + "from rule implementation function in a struct, which are <code>runfiles</code>, " + + "<code>data_runfiles</code>, <code>default_runfiles</code>, <code>files</code>, " + + "<code>output_groups</code>, <code>instrumented_files</code>, and all " + + "<a href=\"skylark-provider.html\">providers</a> that are available on built-in " + + "rules. Each instance of the default provider contains the following standard " + + "fields: <code>data_runfiles</code>, <code>default_runfiles</code>, " + + "<code>files</code>, and <code>files_to_run</code>. The values of these fields " + + "are equivalent to the values of the corresponding fields of the target " + + "the default provider belongs to." ) private static final ClassObjectConstructor defaultInfo = DefaultProvider.SKYLARK_CONSTRUCTOR; @@ -226,7 +228,7 @@ public class SkylarkRuleClassFunctions { ) private static final ClassObjectConstructor actions = ActionsProvider.SKYLARK_CONSTRUCTOR; - @SkylarkSignature(name = "provider", returnType = SkylarkClassObjectConstructor.class, doc = + @SkylarkSignature(name = "provider", returnType = ClassObjectConstructor.class, doc = "Creates a declared provider 'constructor'. The return value of this" + "function can be used to create \"struct-like\" values. Example:<br>" + "<pre class=\"language-python\">data = provider()\n" @@ -236,7 +238,7 @@ public class SkylarkRuleClassFunctions { ) private static final BuiltinFunction provider = new BuiltinFunction("provider") { - public SkylarkClassObjectConstructor invoke(Location location) { + public ClassObjectConstructor invoke(Location location) { return new SkylarkClassObjectConstructor( "<no name>", // name is set on export. location); |