Clarify documentation about outputs.
RELNOTES: None.
@@ -173,20 +173,30 @@ my_rule = rule(
## <a name="output-files"></a> Output files
A target can declare output files, which must be generated by the target's
-actions. There are three ways to create output files:
+actions. Each output file must have exactly one generating action.
+
+There are multiple ways to have declared outputs:
* If the rule is marked `executable`, it creates an output file of the same name
as the rule's. [See example](https://github.com/bazelbuild/examples/blob/master/rules/executable/executable.bzl)
-* The rule can declare default `outputs`, which are always generated.
+* The rule can declare outputs using the `outputs` argument of the
+ [rule](lib/globals.html#rule) function.
[See example](https://github.com/bazelbuild/examples/blob/master/rules/default_outputs/extension.bzl)
-* The rule can have output or output list type attributes. In that case the
- output files come from the actual attribute values.
+* The rule can have [output](lib/attr.html#output) or [output_list](lib/attr.html#output_list)
+ attributes. In that case the output files come from the actual attribute values.
[See example](https://github.com/bazelbuild/examples/blob/master/rules/custom_outputs/extension.bzl)
-Each output file must have exactly one generating action. See the
-[library](lib/ctx.html#outputs) for more context.
+We call them "declared outputs" because they are associated with a label. You
+can refer to declared outputs using a label on the command-line or in a `BUILD`
+file. In the implementation function, use [ctx.outputs](lib/ctx.html#outputs)
+for accessing declared outputs.
+
+The rule can also create extra output files during the analysis phase using the
+[ctx.actions.declare_file](lib/actions.html#declare_file) function. This is
+more flexible, but those files are not declared: they don't have any associated
+label.
## Default outputs
@@ -200,8 +210,8 @@ Every rule has a set of default outputs. This is used:
This is the case, for example, if you use a rule in the `srcs` attribute of a
`genrule`.
-Use the `files` provider to specify the default outputs of a rule.
-If left unspecified, it will contain all the declared outputs.
+In the `DefaultInfo` provider, the `files` field specifies the default outputs
+of a rule. If left unspecified, it will contain all the declared outputs.
```python
def _impl(ctx):
@@ -210,9 +220,12 @@ def _impl(ctx):
```
This can be useful for exposing files generated with
-[ctx.actions.declare_file](lib/actions.html#declare_file). You can also
-have "implicit outputs", i.e., files that are declared in the rule, but
-not in the default outputs (like `_deploy.jar` in `java_binary`).
+[ctx.actions.declare_file](lib/actions.html#declare_file).
+
+An "implicit output" is a declared output that is not in the default outputs. In
+other words, it is not generated by default. Users can refer to its label to
+build the file explicitly. Use the `files` mentioned above if you need implicit
+outputs (like `_deploy.jar` files generated by `java_binary`).
## Actions
