Clarify documentation about "manual" tag
* Emphasize that this only affects the selection of top-level targets to build/test.
* Make it clearer that this means "manual" as in "selected explicitly", this meaning is distinct from whether the target should be run automatically by continuous testing infrastructure.
* Note why such infrastructure should not exclude "manual"-tagged targets unconditionally.
RELNOTES: None.
PiperOrigin-RevId: 319200234
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/tags.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/tags.html
index e665cc4..7660791 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/tags.html
+++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/tags.html
@@ -83,21 +83,25 @@
</p>
<ul>
- <li><code>exclusive</code> keyword will force the test to be run in the
+ <li><code>exclusive</code> will force the test to be run in the
"exclusive" mode, ensuring that no other tests are running at the
same time. Such tests will be executed in serial fashion after all build
activity and non-exclusive tests have been completed. They will also always
run locally and thus without sandboxing.
</li>
- <li><code>manual</code> keyword will force the test target to not be included in target pattern
- wildcards (<code>...</code>, <code>:*</code>, <code>:all</code>, etc); the test target will be
- neither built nor run. It will also be ignored by the <code>test_suite</code> rules that do not
- mention this test explicitly. The only way to build or run such a test is to specify it via an
- explicit target pattern on the command line. Bazel query does not honour
- the <code>manual</code> tag.
+ <li><code>manual</code> keyword will exclude the target from expansion of target pattern wildcards
+ (<code>...</code>, <code>:*</code>, <code>:all</code>, etc.) and <code>test_suite</code> rules
+ which do not list the test explicitly when computing the set of top-level targets to build/run
+ for the <code>build</code>, <code>test</code>, and <code>coverage</code> commands. It does not
+ affect target wildcard or test suite expansion in other contexts, including the
+ <code>query</code> command. Note that <code>manual</code> does not imply that a target should
+ not be built/run automatically by continuous build/test systems. For example, it may be
+ desirable to exclude a target from <code>bazel test ...</code> because it requires specific
+ Bazel flags, but still have it included in properly-configured presubmit or continuous test
+ runs.
- </li>
+ </li>
<li><code>external</code> keyword will force test to be unconditionally
executed (regardless of <code class='flag'>--cache_test_results</code>
