Unclear documentation for JavaInfo transitive
https://docs.bazel.build/versions/master/skylark/lib/JavaInfo.html

It is unclear what the difference is between `transitive_compile_time_jars` and `transitive_deps`.

It is unclear what the difference is between `transitive_runtime_deps` and `transitive_runtime_jars`.
src/main/java/com/google/devtools/build/lib/skylarkbuildapi/java/JavaInfoApi.java
src/main/java/com/google/devtools/build/lib/skylarkbuildapi/java/JavaInfoApi.java
diff --git a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/java/JavaInfoApi.java b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/java/JavaInfoApi.java
index e05196d42418c1..1ccb862e7bf738 100644
--- a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/java/JavaInfoApi.java
+++ b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/java/JavaInfoApi.java
@@ -35,60 +35,63 @@
  */
 @SkylarkModule(
     name = "JavaInfo",
-    doc = "Encapsulates all information provided by Java rules.",
+    doc = "A provider encapsulating information about Java and Java-like targets.",
     category = SkylarkModuleCategory.PROVIDER)
 public interface JavaInfoApi <FileT extends FileApi> extends StructApi {
 
   @SkylarkCallable(
       name = "transitive_runtime_jars",
-      doc = "Depset of runtime jars required by this target",
+      doc = "Returns a transitive set of Jars required on the target's runtime classpath. Returns the same as "
+          + "<code><a class=\"anchor\" href=\"JavaInfo.html#transitive_runtime_deps\">JavaInfo.transitive_runtime_deps</a></code> "
+          + "for legacy reasons.",
       structField = true
   )
   public SkylarkNestedSet getTransitiveRuntimeJars();
 
   @SkylarkCallable(
       name = "transitive_compile_time_jars",
-      doc =
-          "Depset of compile time jars recursively required by this target. See `compile_jars` "
-              + "for more details.",
+      doc = "Returns the transitive set of Jars required to build the target. Returns the same as "
+          + "<code><a class=\"anchor\" href=\"JavaInfo.html#transitive_deps\">JavaInfo.transitive_deps</a></code> "
+          + "for legacy reasons.",
       structField = true)
   public SkylarkNestedSet getTransitiveCompileTimeJars();
 
   @SkylarkCallable(
       name = "compile_jars",
       doc =
-          "Returns the compile time jars required by this target directly. They can be: <ul><li>"
-              + " interface jars (ijars), if an ijar tool was used</li><li> normal full jars, if"
-              + " no ijar action was requested</li><li> both ijars and normal full jars, if this"
-              + " provider was created by merging two or more providers created with different"
-              + " ijar requests </li> </ul>",
+          "Returns the Jars required by this target directly at compile time. They can be interface jars "
+          + "(ijar or hjar), regular jars or both, depending on whether rule implementations chose to create "
+          + "interface jars or not.",
       structField = true)
   public SkylarkNestedSet getCompileTimeJars();
 
   @SkylarkCallable(
       name = "full_compile_jars",
       doc =
-          "Returns the full compile time jars required by this target directly. They can be"
-              + " <ul><li> the corresponding normal full jars of the ijars returned by"
-              + " `compile_jars`</li><li> the normal full jars returned by"
-              + " `compile_jars`</li></ul>Note: `compile_jars` can return a mix of ijars and"
-              + " normal full jars. In that case, `full_compile_jars` returns the corresponding"
-              + " full jars of the ijars and the remaining normal full jars in `compile_jars`.",
+          "Returns the regular, full compile time Jars required by this target directly. They can be"
+              + " <ul><li> the corresponding regular Jars of the interface Jars returned by"
+              + " <code><a class=\"anchor\" href=\"JavaInfo.html#compile_jars\">JavaInfo.compile_jars</a></code></li>"
+              + "<li> the regular (full) Jars returned by"
+              + " <code><a class=\"anchor\" href=\"JavaInfo.html#compile_jars\">JavaInfo.compile_jars</a></code></li></ul>"
+              + "<p>Note: <code><a class=\"anchor\" href=\"JavaInfo.html#compile_jars\">JavaInfo.compile_jars</a></code> "
+              + "can return a mix of interface Jars and regular Jars."
+              + "<p>Only use this method if interface Jars don't work with your rule set(s) (e.g. some Scala targets)"
+              + " If you're working with Java-only targets it's preferable to use interface Jars via "
+              + "<code><a class=\"anchor\" href=\"JavaInfo.html#compile_jars\">JavaInfo.compile_jars</a></code></li>",
       structField = true)
   public SkylarkNestedSet getFullCompileTimeJars();
 
   @SkylarkCallable(
       name = "source_jars",
-      doc = "Returns a list of jar files containing all the uncompiled source files (including "
-      + "those generated by annotations) from the target itself, i.e. NOT including the sources of "
-      + "the transitive dependencies",
+      doc = "Returns a list of Jars with all the source files (including those generated by annotations) of the target "
+              + " itself, i.e. NOT including the sources of the transitive dependencies.",
       structField = true
   )
   public SkylarkList<FileT> getSourceJars();
 
   @SkylarkCallable(
     name = "outputs",
-    doc = "Returns information about outputs of this Java target.",
+    doc = "Returns information about outputs of this Java/Java-like target.",
     structField = true,
     allowReturnNones = true
   )
@@ -98,7 +101,7 @@ public interface JavaInfoApi <FileT extends FileApi> extends StructApi {
       name = "annotation_processing",
       structField = true,
       allowReturnNones = true,
-      doc = "Returns information about annotation processing for this Java target."
+      doc = "Returns information about annotation processing for this Java/Java-like target."
   )
   public JavaAnnotationProcessingApi<?> getGenJarsProvider();
 
@@ -106,34 +109,37 @@ public interface JavaInfoApi <FileT extends FileApi> extends StructApi {
     name = "compilation_info",
     structField = true,
     allowReturnNones = true,
-    doc = "Returns compilation information for this Java target."
+    doc = "Returns compilation information for this Java/Java-like target."
   )
   public JavaCompilationInfoProviderApi<?> getCompilationInfoProvider();
 
   @SkylarkCallable(
       name = "runtime_output_jars",
-      doc = "Returns the runtime output jars provided by this Java target.",
+      doc = "Returns a list of runtime Jars created by this Java/Java-like target.",
       structField = true)
   public SkylarkList<FileT> getRuntimeOutputJars();
 
   @SkylarkCallable(
     name = "transitive_deps",
-    doc = "Returns the transitive set of Jars required to build the target.",
+    doc = "Returns the transitive set of Jars required to build the target. Returns the same as "
+          + "<code><a class=\"anchor\" href=\"JavaInfo.html#transitive_compile_time_jars\">JavaInfo.transitive_compile_time_jars</a></code> "
+          + "for legacy reasons.",
     structField = true
   )
   public NestedSet<FileT> getTransitiveDeps();
 
   @SkylarkCallable(
     name = "transitive_runtime_deps",
-    doc = "Returns the transitive set of Jars required on the target's runtime classpath.",
+    doc = "Returns the transitive set of Jars required on the target's runtime classpath. Returns the same as "
+            + "<code><a class=\"anchor\" href=\"JavaInfo.html#transitive_runtime_jars\">JavaInfo.transitive_runtime_jars</a></code>"
+            + " for legacy reasons.",
     structField = true
   )
   public NestedSet<FileT> getTransitiveRuntimeDeps();
 
   @SkylarkCallable(
     name = "transitive_source_jars",
-    doc = "Returns the Jars containing Java source files for the target "
-            + "and all of its transitive dependencies.",
+    doc = "Returns the Jars containing source files of the current target and all of its transitive dependencies.",
     structField = true
   )
   public NestedSet<FileT> getTransitiveSourceJars();
@@ -141,7 +147,7 @@ public interface JavaInfoApi <FileT extends FileApi> extends StructApi {
   @SkylarkCallable(
       name = "transitive_exports",
       structField = true,
-      doc = "Returns transitive set of labels that are being exported from this rule."
+      doc = "Returns a set of labels that are being exported from this rule transitively."
   )
   public NestedSet<Label> getTransitiveExports();
 
