More documentation for j2objc_library.

--
MOS_MIGRATED_REVID=103333849

2 files changed, 34 insertions, 4 deletions

diff --git a/src/main/java/com/google/devtools/build/lib/bazel/rules/objc/BazelJ2ObjcLibraryRule.java b/src/main/java/com/google/devtools/build/lib/bazel/rules/objc/BazelJ2ObjcLibraryRule.java
index 0a73475cc1..2025531eff 100644
--- a/src/main/java/com/google/devtools/build/lib/bazel/rules/objc/BazelJ2ObjcLibraryRule.java
+++ b/src/main/java/com/google/devtools/build/lib/bazel/rules/objc/BazelJ2ObjcLibraryRule.java
@@ -41,6 +41,24 @@ public class BazelJ2ObjcLibraryRule implements RuleDefinition {
           and <code>java_import</code> targets that contain
           Java files to be transpiled to Objective-C.
           ${SYNOPSIS}
+          <p>All <code>java_library</code> and <code>java_import</code> targets that can be reached
+          transitively through <code>exports</code>, <code>deps</code> and <code>runtime_deps</code>
+          will be translated and compiled. Currently there is no support for files generated by Java
+          annotation processing or <code>java_import</code> targets with no <code>srcjar</code>
+          specified.
+          </p>
+          <p>The J2ObjC translation works differently depending on the type of source Java source
+          files included in the transitive closure. For each .java source files included in
+          <code>srcs</code> of <code>java_library</code>, a corresponding .h and .m source file
+          will be generated. For each source jar included in <code>srcs</code> of
+          <code>java_library</code> or <code>srcjar</code> of <code>java_import</code>, a
+          corresponding .h and .m source file will be generated with all the code for that jar.
+          </p>
+          <p>Users can import the J2ObjC-generated header files in their code. The import paths for
+          these files are the root-relative path of the original Java artifacts. For example,
+          <code>//some/package/foo.java</code> has an import path of <code>some/package/foo.h</code>
+          and <code>//some/package/bar.srcjar</code> has <code>some/package/bar.h</code
+          </p>
           <!-- #END_BLAZE_RULE.ATTRIBUTE -->*/
         .add(attr("deps", LABEL_LIST)
             .aspect(J2ObjcAspect.class)
diff --git a/src/main/java/com/google/devtools/build/lib/rules/objc/J2ObjcLibraryBaseRule.java b/src/main/java/com/google/devtools/build/lib/rules/objc/J2ObjcLibraryBaseRule.java
index c9c5f33630..537cccd010 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/objc/J2ObjcLibraryBaseRule.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/objc/J2ObjcLibraryBaseRule.java
@@ -64,10 +64,22 @@ public class J2ObjcLibraryBaseRule implements RuleDefinition {
 
 ${ATTRIBUTE_SIGNATURE}
 
-<p>This rule uses <a href="https://github.com/google/j2objc">J2ObjC</a>
-to translate Java source files to Objective-C, which then can be used used as dependencies of
-<code>objc_library</code> and <code>objc_binary</code> rules. More information about J2ObjC
-can be found <a href="http://j2objc.org">here</a>.
+<p> This rule uses <a href="https://github.com/google/j2objc">J2ObjC</a> to translate Java source
+files to Objective-C, which then can be used used as dependencies of objc_library and objc_binary
+rules. Detailed information about J2ObjC itself can be found at  <a href="http://j2objc.org">the
+J2ObjC site</a>
+</p>
+<p>Custom J2ObjC transpilation flags can be specified using the build flag
+<code>--j2objc_translation_flags</code> in the command line.
+</p>
+<p>Please note that currently the translated files included in a j2objc_library target will be
+compiled using the same compilation configuration as the top level objc_binary target that depends
+on the j2objc_library target.
+</p>
+<p>Plus, generated code is de-duplicated at target level, not source level. If you have two
+different Java targets that include the same Java source files, you may see a duplicate symbol error
+at link time. The correct way to resolve this issue is to move the shared Java source files into a
+separate common target that can be depended upon.
 </p>