From e812e4136260fea8e3f10a5ecb759fdb401782ee Mon Sep 17 00:00:00 2001
From: Lukacs Berki <lberki@google.com>
Date: Fri, 14 Aug 2015 14:38:01 +0000
Subject: Document the Android rules in Bazel.

--
MOS_MIGRATED_REVID=100672806
---
 .../rules/android/BazelAndroidBinaryRule.java      | 54 ++++++++++++++++++++++
 .../rules/android/BazelAndroidLibraryRule.java     | 30 ++++++++++++
 2 files changed, 84 insertions(+)

(limited to 'src')

diff --git a/src/main/java/com/google/devtools/build/lib/bazel/rules/android/BazelAndroidBinaryRule.java b/src/main/java/com/google/devtools/build/lib/bazel/rules/android/BazelAndroidBinaryRule.java
index d3e25ca2e0..69c7ac142b 100644
--- a/src/main/java/com/google/devtools/build/lib/bazel/rules/android/BazelAndroidBinaryRule.java
+++ b/src/main/java/com/google/devtools/build/lib/bazel/rules/android/BazelAndroidBinaryRule.java
@@ -36,6 +36,43 @@ public class BazelAndroidBinaryRule implements RuleDefinition {
         .add(attr(":cc_toolchain_split", Type.LABEL)
             .cfg(AndroidRuleClasses.ANDROID_SPLIT_TRANSITION)
             .value(BazelCppRuleClasses.CC_TOOLCHAIN))
+        /* <!-- #BLAZE_RULE(android_binary).IMPLICIT_OUTPUTS -->
+         <ul>
+         <li><code><var>name</var>.apk</code>: An Android application
+          package file signed with debug keys and
+          <a href="http://developer.android.com/guide/developing/tools/zipalign.html">
+          zipaligned</a>, it could be used to develop and debug your application.
+          You cannot release your application when signed with the debug keys.</li>
+          <li><code><var>name</var>_unsigned.apk</code>: An unsigned version of the
+            above file that could be signed with the release keys before release to
+            the public.
+          </li>
+          <li><code><var>name</var>_deploy.jar</code>: A Java archive containing the
+            transitive closure of this target.
+            <p>The deploy jar contains all the classes that would be found by a
+            classloader that searched the runtime classpath of this target
+            from beginning to end.</p>
+          </li>
+          <li><code><var>name</var>_proguard.jar</code>: A Java archive containing
+            the result of running ProGuard on the
+            <code><var>name</var>_deploy.jar</code>.
+            This output is only produced if
+            <a href="#android_binary.proguard_specs">proguard_specs</a> attribute is
+            specified.
+          </li>
+          <li><code><var>name</var>_proguard.map</code>: A mapping file result of
+            running ProGuard on the <code><var>name</var>_deploy.jar</code>.
+            This output is only produced if
+            <a href="#android_binary.proguard_specs">proguard_specs</a> attribute is
+            specified and
+            <a href="#android_binary.proguard_generate_mapping">proguard_generate_mapping</a>
+            is set.
+          </li>
+          <li><code><var>name</var>-gen.jar</code>: An archive containing the class files
+            for source files generated by annotation processors ("gen jar").
+          </li>
+        </ul>
+        <!-- #END_BLAZE_RULE.IMPLICIT_OUTPUTS --> */
         .setImplicitOutputsFunction(AndroidRuleClasses.ANDROID_BINARY_IMPLICIT_OUTPUTS)
         .build();
   }
@@ -52,3 +89,20 @@ public class BazelAndroidBinaryRule implements RuleDefinition {
         .build();
   }
 }
+/*<!-- #BLAZE_RULE (NAME = android_binary, TYPE = BINARY, FAMILY = Android) -->
+
+${ATTRIBUTE_SIGNATURE}
+
+<p>
+  Produces Android application package files (.apk).
+</p>
+
+${IMPLICIT_OUTPUTS}
+
+${ATTRIBUTE_DEFINITION}
+
+<h4 id="android_binary_examples">Examples</h4>
+<p>Examples of Android rules can be found in the <code>examples/android</code> directory of the
+Bazel source tree.
+
+<!-- #END_BLAZE_RULE -->*/
diff --git a/src/main/java/com/google/devtools/build/lib/bazel/rules/android/BazelAndroidLibraryRule.java b/src/main/java/com/google/devtools/build/lib/bazel/rules/android/BazelAndroidLibraryRule.java
index b7a7ae2e43..6a6c79e9fa 100644
--- a/src/main/java/com/google/devtools/build/lib/bazel/rules/android/BazelAndroidLibraryRule.java
+++ b/src/main/java/com/google/devtools/build/lib/bazel/rules/android/BazelAndroidLibraryRule.java
@@ -30,8 +30,19 @@ public class BazelAndroidLibraryRule implements RuleDefinition {
   @Override
   public RuleClass build(Builder builder, RuleDefinitionEnvironment env) {
     return builder
+        /* <!-- #BLAZE_RULE(android_library).IMPLICIT_OUTPUTS -->
+        <ul>
+          <li><code>lib<var>name</var>.jar</code>: A Java archive.</li>
+          <li><code>lib<var>name</var>-src.jar</code>: An archive containing the
+          sources ("source jar").</li>
+          <li><code>lib<var>name</var>-gen.jar</code>: An archive containing the
+            class files for source files generated by annotation processors
+            ("gen jar").</li>
+        </ul>
+        <!-- #END_BLAZE_RULE.IMPLICIT_OUTPUTS --> */
         .setImplicitOutputsFunction(AndroidRuleClasses.ANDROID_LIBRARY_IMPLICIT_OUTPUTS)
         .build();
+
   }
 
   @Override
@@ -45,3 +56,22 @@ public class BazelAndroidLibraryRule implements RuleDefinition {
         .build();
   }
 }
+
+/*<!-- #BLAZE_RULE (NAME = android_library, TYPE = LIBRARY, FAMILY = Android) -->
+
+${ATTRIBUTE_SIGNATURE}
+
+<p>This rule compiles and archives its sources into a <code>.jar</code> file.
+  The Android runtime library <code>android.jar</code> is implicitly put on
+  the compilation class path.
+</p>
+
+${IMPLICIT_OUTPUTS}
+
+${ATTRIBUTE_DEFINITION}
+
+<h4 id="android_library_examples">Examples</h4>
+<p>Examples of Android rules can be found in the <code>examples/android</code> directory of the
+Bazel source tree.
+
+<!-- #END_BLAZE_RULE -->*/
-- 
cgit v1.2.3