From 2b81545de77afb691c3d5f4243f60efe8fb97d1b Mon Sep 17 00:00:00 2001
From: lberki <lberki@google.com>
Date: Tue, 10 Apr 2018 05:59:54 -0700
Subject: Improve documentation of genquery.

RELNOTES: None.
PiperOrigin-RevId: 192274504
---
 .../build/lib/rules/genquery/GenQuery.java         |  2 ++
 .../build/lib/rules/genquery/GenQueryRule.java     | 25 ++++++++++++----------
 2 files changed, 16 insertions(+), 11 deletions(-)

(limited to 'src/main')

diff --git a/src/main/java/com/google/devtools/build/lib/rules/genquery/GenQuery.java b/src/main/java/com/google/devtools/build/lib/rules/genquery/GenQuery.java
index 5149f50df8..95c45dea83 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/genquery/GenQuery.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/genquery/GenQuery.java
@@ -123,6 +123,8 @@ public class GenQuery implements RuleConfiguredTargetFactory {
 
     // Parsed query options
     QueryOptions queryOptions = optionsParser.getOptions(QueryOptions.class);
+    // If you change the list of options here, also change the documentation of genquery.opts in
+    // GenQueryRule.java .
     if (optionsParser.getOptions(KeepGoingOption.class).keepGoing) {
       ruleContext.attributeError("opts", "option --keep_going is not allowed");
       return null;
diff --git a/src/main/java/com/google/devtools/build/lib/rules/genquery/GenQueryRule.java b/src/main/java/com/google/devtools/build/lib/rules/genquery/GenQueryRule.java
index 7565717e57..ce273b0078 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/genquery/GenQueryRule.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/genquery/GenQueryRule.java
@@ -34,26 +34,29 @@ public final class GenQueryRule implements RuleDefinition {
   public RuleClass build(Builder builder, RuleDefinitionEnvironment env) {
     return builder
         /* <!-- #BLAZE_RULE(genquery).ATTRIBUTE(scope) -->
-        The scope of the query. The query is not allowed to
-        touch targets outside the transitive closure of these targets.
+        The scope of the query. The query is not allowed to touch targets outside the transitive
+        closure of these targets.
         <!-- #END_BLAZE_RULE.ATTRIBUTE --> */
         .add(attr("scope", LABEL_LIST).mandatory().legacyAllowAnyFileType())
         /* <!-- #BLAZE_RULE(genquery).ATTRIBUTE(strict) -->
-        If true, targets whose queries escape the transitive closure of their
-        scopes will fail to build. If false, Blaze will print a warning and skip
-        whatever query path led it outside of the scope, while completing the rest
-        of the query.
+        If true, targets whose queries escape the transitive closure of their scopes will fail to
+        build. If false, Blaze will print a warning and skip whatever query path led it outside of
+        the scope, while completing the rest of the query.
         <!-- #END_BLAZE_RULE.ATTRIBUTE --> */
         .add(attr("strict", BOOLEAN).value(true))
         /* <!-- #BLAZE_RULE(genquery).ATTRIBUTE(expression) -->
-        The query to be executed.
+        The query to be executed. In contrast to the command line and other places in BUILD files,
+        labels here are resolved relative to the root directory of the workspace. For example, the
+        label <code>:b</code> in this attribute in the file <code>a/BUILD</code> will refer to the
+        target <code>//:b</code>.
         <!-- #END_BLAZE_RULE.ATTRIBUTE --> */
         .add(attr("expression", STRING).mandatory())
         /* <!-- #BLAZE_RULE(genquery).ATTRIBUTE(opts) -->
-        The options that are passed to the query engine.
-        These correspond to the command line options that can be passed to
-        <code>blaze query</code>. The only query options that are not allowed here
-        are <code>--keep_going</code> and <code>--order_output</code>.
+        The options that are passed to the query engine. These correspond to the command line
+        options that can be passed to <code>blaze query</code>. Some query options are not allowed
+        here: <code>--keep_going</code>, <code>--query_file</code>, <code>--universe_scope</code>,
+        <code>--order_results</code> and <code>--order_output</code>. Options not specified here
+        will have their default values just like on the command line of <code>blaze query</code>.
         <!-- #END_BLAZE_RULE.ATTRIBUTE --> */
         .add(attr("opts", STRING_LIST))
         .build();
-- 
cgit v1.2.3