From 642d7d4e93486e7fefa3c8ec01f56c48a8b590ca Mon Sep 17 00:00:00 2001
From: Googler <noreply@google.com>
Date: Thu, 12 Mar 2015 15:48:09 +0000
Subject: BazelActionListenerRule is documented.

--
MOS_MIGRATED_REVID=88444163
---
 .../rules/common/BazelActionListenerRule.java      | 64 ++++++++++++++++++++++
 1 file changed, 64 insertions(+)

(limited to 'src/main/java/com/google/devtools/build')

diff --git a/src/main/java/com/google/devtools/build/lib/bazel/rules/common/BazelActionListenerRule.java b/src/main/java/com/google/devtools/build/lib/bazel/rules/common/BazelActionListenerRule.java
index eba1553ac8..0865c34bbc 100644
--- a/src/main/java/com/google/devtools/build/lib/bazel/rules/common/BazelActionListenerRule.java
+++ b/src/main/java/com/google/devtools/build/lib/bazel/rules/common/BazelActionListenerRule.java
@@ -35,7 +35,22 @@ public final class BazelActionListenerRule implements RuleDefinition {
   @Override
   public RuleClass build(Builder builder, RuleDefinitionEnvironment environment) {
     return builder
+        /*<!-- #BLAZE_RULE(action_listener).ATTRIBUTE(mnemonics) -->
+        A list of action mnemonics this <code>action_listener</code> should listen
+        for, e.g. <code>[ "Javac" ]</code>.
+        ${SYNOPSIS}
+        <p>
+          Mnemonics are not a public interface.
+          There's no guarantee that the mnemonics and their actions don't change.
+        </p>
+        <!-- #END_BLAZE_RULE.ATTRIBUTE -->*/
         .add(attr("mnemonics", STRING_LIST).mandatory())
+        /*<!-- #BLAZE_RULE(action_listener).ATTRIBUTE(extra_actions) -->
+        A list of <code><a href="#extra_action">extra_action</a></code> targets
+        this <code>action_listener</code> should add to the build graph.
+        ${SYNOPSIS}
+        E.g. <code>[ "//my/tools:analyzer" ]</code>.
+        <!-- #END_BLAZE_RULE.ATTRIBUTE -->*/
         .add(attr("extra_actions", LABEL_LIST).mandatory()
             .allowedRuleClasses("extra_action")
             .allowedFileTypes())
@@ -45,3 +60,52 @@ public final class BazelActionListenerRule implements RuleDefinition {
         .build();
   }
 }
+
+/*<!-- #BLAZE_RULE (NAME = action_listener, TYPE = BINARY, FAMILY = Extra Actions)[GENERIC_RULE] -->
+
+<p>
+  <b>DISCLAIMER:</b>
+  This is an experimental feature, expect breaking changes when
+  implementing an <code>action_listener</code>/<code>extra_action</code>.
+</p>
+
+${ATTRIBUTE_SIGNATURE}
+
+<p>
+  An <code>action_listener</code> rule doesn't produce any output itself.
+  Instead, it allows tool developers to insert
+  <a href="#extra_action"><code>extra_action</code></a>s into the build system,
+  by providing a mapping from action to <a href="#extra_action"><code>extra_action</code></a>.
+</p>
+
+<p>
+  This rule's arguments map action mnemonics to
+  <a href="#extra_action"><code>extra_action</code></a> rules.
+</p>
+
+<p>
+  By specifying the option <a href="bazel-user-manual.html#flag--experimental_action_listener">
+  <code>--experimental_action_listener=&lt;label&gt;</code></a>,
+  the build will use the specified <code>action_listener</code> to insert
+  <a href="#extra_action"><code>extra_action</code></a>s into the build graph.
+</p>
+
+${ATTRIBUTE_DEFINITION}
+
+<h4 id="action_listener_example">Example</h4>
+<pre>
+    action_listener(name = "index_all_languages",
+                    mnemonics = [ "Javac", "CppCompile" ],
+                    extra_actions = [ ":indexer" ])
+
+    action_listener(name = "index_java",
+                    mnemonics = [ "Javac" ],
+                    extra_actions = [ ":indexer" ])
+
+    extra_action(name = "indexer",
+                 tools = [ "//my/tools:indexer" ],
+                 cmd = "$(location //my/tools:indexer)" +
+                       "--extra_action_file=$(EXTRA_ACTION_FILE)")
+</pre>
+
+<!-- #END_BLAZE_RULE -->*/
-- 
cgit v1.2.3