Build encyclopedia: mark attributes that don't work with

select() as "nonconfigurable", polish up general configurable
attributes docs.

--
MOS_MIGRATED_REVID=127440164

3 files changed, 45 insertions, 7 deletions

diff --git a/src/main/java/com/google/devtools/build/docgen/RuleDocumentationAttribute.java b/src/main/java/com/google/devtools/build/docgen/RuleDocumentationAttribute.java
index fa53ca80e6..02357ff3f6 100644
--- a/src/main/java/com/google/devtools/build/docgen/RuleDocumentationAttribute.java
+++ b/src/main/java/com/google/devtools/build/docgen/RuleDocumentationAttribute.java
@@ -180,6 +180,7 @@ public class RuleDocumentationAttribute implements Comparable<RuleDocumentationA
     StringBuilder sb = new StringBuilder()
         .append(TYPE_DESC.get(attribute.getType()))
         .append("; " + (attribute.isMandatory() ? "required" : "optional"))
+        .append(!attribute.isConfigurable() ? "; nonconfigurable" : "")
         .append(getDefaultValue());
     return sb.toString();
   }
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/be/common-definitions.vm b/src/main/java/com/google/devtools/build/docgen/templates/be/common-definitions.vm
index 8a49b6f5aa..ff9e2a5875 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/be/common-definitions.vm
+++ b/src/main/java/com/google/devtools/build/docgen/templates/be/common-definitions.vm
@@ -109,13 +109,50 @@ labels attribute.
 <h2 id="configurable-attributes">Configurable attributes</h2>
 
 <p>
-  Most rule attributes can be "configured" so their values depend on Bazel
-  command-line flags. This can be used, for example, to declare
+  Most attributes can be "configured" so their values depend on the flags passed
+  at the command line. This can be used, for example, to declare
   platform-dependent <code>srcs</code> or custom compiler flags depending on the
   <a href="../bazel-user-manual.html#flag--compilation_mode">compilation
   mode</a>.
 </p>
 
+<h4>Example</h4>
+
+<pre class="code">
+cc_library(
+    name = "multiplatform_lib",
+    srcs = select({
+        ":x86_mode": ["x86_impl.cc"],
+        ":arm_mode": ["arm_impl.cc"]
+    })
+)
+config_setting(
+    name = "x86_mode",
+    values = { "cpu": "x86" }
+)
+config_setting(
+    name = "arm_mode",
+    values = { "cpu": "arm" }
+)
+</pre>
+
+<p>
+  An attribute is made configurable by assigning it to a <code>select</code>.
+  This makes its value depend on which <code>config_setting</code> matches
+  the build. For example, <code>bazel build :multiplatform_lib --cpu=arm</code>
+  sets <code>multiplatform_lib</code>'s <code>srcs</code> to
+  <code>["arm_impl.cc"]</code>, while <code>bazel build :multiplatform_lib
+  --cpu=x86</code> sets <code>srcs</code> to <code>["x86_impl.cc"]</code>.
+</p>
+
+<p>
+  See the definitions of
+  <a href="functions.html#select">select</a> and
+  <a href="general.html#config_setting">config_setting</a> for more details.
+  Attributes marked <code>nonconfigurable</code> in their documentation cannot
+  use this feature (usually because Bazel has to know their values before flags
+  have been parsed).
+
 </p>
 
 <h2 id="implicit-outputs">Implicit output targets</h2>
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/be/functions.vm b/src/main/java/com/google/devtools/build/docgen/templates/be/functions.vm
index 3bea6a4c26..780716cfe1 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/be/functions.vm
+++ b/src/main/java/com/google/devtools/build/docgen/templates/be/functions.vm
@@ -589,10 +589,9 @@ $ bazel query '//foo:all' | sort
 
 <pre>select({conditionA: valuesA, conditionB: valuesB, ...})</pre>
 
-<p><code>select()</code> is the helper function that makes an
-  attribute for a
-  rule <a href="common-definitions.html#configurable-attributes">configurable</a>. It can
-  replace the right-hand side of
+<p><code>select()</code> is the helper function that makes a rule attribute
+  <a href="common-definitions.html#configurable-attributes">configurable</a>.
+  It can replace the right-hand side of
 
   <i>almost</i>
   any attribute assignment so that the attribute's value depends on the
@@ -648,7 +647,8 @@ sh_binary(
     srcs = select({ ":conditionA": ["a.sh"]}) + select({ ":conditionB":
     ["b.sh"]})</code> are valid expressions.
   </li>
-  <li><code>select</code> works with most, but not all, attributes.
+  <li><code>select</code> works with most, but not all, attributes. Incompatible
+  attributes are marked <code>nonconfigurable</code> in their documentation.
 
   </li>
 </ul>