Fix incomplete documentation change
This finishes a partial change erroneously submitted as part of
The full outputs map behavior is still not fully described because its implementation is too complex. That requires a separate discussion.
RELNOTES: None
@@ -417,26 +417,26 @@ public class SkylarkRuleClassFunctions {
+ "</a>attributes, the user does not specify the labels for these files. See the "
+ "<a href='../rules.$DOC_EXT#files'>Rules page</a> for more on predeclared "
+ "outputs."
- + "<p>The value of this argument is a dictionary. Each entry creates a predeclared "
- + "output where the key is an identifier and the value helps determine the "
- + "output's label. In the rule's implementation function, the identifier becomes "
- + "the field name used to access the output's <a href='File.html'><code>File</code>"
- + "</a> in <a href='ctx.html#outputs'><code>ctx.outputs</code></a>."
- + "<p>The output's label has the same package as the rule, and the part after the "
- + "package is determined by the dict entry's value. If this value is a string, "
- + "then it is interpreted as a template, where substitution placeholders of the "
- + "form <code>\"%{ATTR}\"</code> are replaced by the value of the string attribute "
- + "named <code>ATTR</code>. (For this purpose, the rule's <code>name</code> is "
- + "also considered an attribute.) For example, the outputs dict "
- + "<code>{\"bin\": \"%{name}.exe\"} predeclares an output with"
- + "</code>. <br>"
- + "The dictionary key becomes an attribute in <code>ctx.outputs</code>. "
- + "Similar to computed dependency rule attributes, you can also specify the "
- + "name of a function that returns the dictionary. This function can access "
- + "all rule attributes that are listed as parameters in its function "
- + "signature. For example, <code>outputs = _my_func</code> with "
- + "<code>def _my_func(srcs, deps):</code> has access to the attributes "
- + "'srcs' and 'deps' (if defined)."
+ + "<p>The value of this argument is either a dictionary or a callback function "
+ + "that produces a dictionary. The callback works similar to computed dependency "
+ + "attributes: The function's parameter names are matched against the rule's "
+ + "attributes, so for example if you pass <code>outputs = _my_func</code> with the "
+ + "definition <code>def _my_func(srcs, deps): ...</code>, the function has access "
+ + "to the attributes <code>srcs</code> and <code>deps</code>. Whether the "
+ + "dictionary is specified directly or via a function, it is interpreted as "
+ + "follows."
+ + "<p>Each entry in the dictionary creates a predeclared output where the key is "
+ + "an identifier and the value is a string template that determines the output's "
+ + "label. In the rule's implementation function, the identifier becomes the field "
+ + "name used to access the output's <a href='File.html'><code>File</code></a> in "
+ + "<a href='ctx.html#outputs'><code>ctx.outputs</code></a>. The output's label has "
+ + "the same package as the rule, and the part after the package is produced by "
+ + "substituting each placeholder of the form <code>\"%{ATTR}\"</code> with the "
+ + "value of the attribute <code>ATTR</code>. In practice, the most common "
+ + "substitution placeholder is <code>\"%{name}\"</code>. For example, for a target "
+ + "named \"foo\", the outputs dict <code>{\"bin\": \"%{name}.exe\"}</code> "
+ + "predeclares an output named <code>foo.exe</code> that is accessable in the "
+ + "implementation function as <code>ctx.outputs.bin</code>."
),
@Param(
name = "executable",
