Cleanup in Android/C++/Java providers documentation

RELNOTES: None.
PiperOrigin-RevId: 162205838

3 files changed, 32 insertions, 27 deletions

diff --git a/src/main/java/com/google/devtools/build/lib/rules/android/AndroidSkylarkApiProvider.java b/src/main/java/com/google/devtools/build/lib/rules/android/AndroidSkylarkApiProvider.java
index edf6f2a08f..3a1f321bff 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/android/AndroidSkylarkApiProvider.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/android/AndroidSkylarkApiProvider.java
@@ -41,7 +41,8 @@ import javax.annotation.Nullable;
   category = SkylarkModuleCategory.PROVIDER,
   doc =
       "Provides access to information about Android rules. Every Android-related target provides "
-          + "this struct, accessible as a 'android' field on a Target struct."
+          + "this struct, accessible as a <code>android</code> field on a "
+          + "<a href=\"Target.html\">target</a>."
 )
 @Immutable
 public class AndroidSkylarkApiProvider extends SkylarkApiProvider {
@@ -98,9 +99,9 @@ public class AndroidSkylarkApiProvider extends SkylarkApiProvider {
     name = "native_libs",
     structField = true,
     doc =
-        "Returns the native libraries as a map of the libraries' architecture as a String to a "
-            + "set of the native library artifacts, or the empty map if there are no native "
-            + "libraries."
+        "Returns the native libraries as a dictionary of the libraries' architecture as a string "
+            + "to a set of the native library files, or the empty dictionary if there are no "
+            + "native libraries."
   )
   public ImmutableMap<String, NestedSet<Artifact>> getNativeLibs() {
     return getIdeInfoProvider().getNativeLibs();
@@ -128,7 +129,7 @@ public class AndroidSkylarkApiProvider extends SkylarkApiProvider {
   @SkylarkCallable(
     name = "defines_resources",
     structField = true,
-    doc = "Returns true if the target defines any Android resources directly."
+    doc = "Returns <code>True</code> if the target defines any Android resources directly."
   )
   public boolean definesAndroidResources() {
     return getIdeInfoProvider().definesAndroidResources();
diff --git a/src/main/java/com/google/devtools/build/lib/rules/cpp/CcSkylarkApiProvider.java b/src/main/java/com/google/devtools/build/lib/rules/cpp/CcSkylarkApiProvider.java
index b540dee5f8..f93774e053 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/cpp/CcSkylarkApiProvider.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/cpp/CcSkylarkApiProvider.java
@@ -33,8 +33,8 @@ import com.google.devtools.build.lib.vfs.PathFragment;
   category = SkylarkModuleCategory.PROVIDER,
   doc =
       "Provides access to information about C++ rules.  "
-          + "Every C++-related target provides this struct, accessible as a 'cc' field on "
-          + "a Target struct."
+          + "Every C++-related target provides this struct, accessible as a <code>cc</code> field "
+          + "on <a href=\"Target.html\">target</a>."
 )
 public final class CcSkylarkApiProvider extends SkylarkApiProvider {
   /** The name of the field in Skylark used to access this class. */
@@ -44,8 +44,9 @@ public final class CcSkylarkApiProvider extends SkylarkApiProvider {
       name = "transitive_headers",
       structField = true,
       doc =
-          "Returns the immutable set of headers that have been declared in the <code>src</code> "
-              + "or <code>headers</code> attribute (possibly empty but never None).")
+          "Returns a <a href=\"depset.html\">depset</a> of headers that have been declared in the "
+              + " <code>src</code> or <code>headers</code> attribute"
+              + "(possibly empty but never <code>None</code>).")
   public NestedSet<Artifact> getTransitiveHeaders() {
     CppCompilationContext ccContext = getInfo().getProvider(CppCompilationContext.class);
     return ccContext.getDeclaredIncludeSrcs();
@@ -55,9 +56,10 @@ public final class CcSkylarkApiProvider extends SkylarkApiProvider {
       name = "libs",
       structField = true,
       doc =
-          "Returns the immutable set of libraries for either "
-              + "FULLY STATIC mode (linkopts=[\"-static\"]) or MOSTLY STATIC mode (linkstatic=1) "
-              + "(possibly empty but never None)")
+          "Returns the <a href=\"depset.html\">depset</a> of libraries for either "
+              + "<code>FULLY STATIC</code> mode (<code>linkopts=[\"-static\"]</code>) or "
+              + "<code>MOSTLY STATIC</code> mode (<code>linkstatic=1</code>) "
+              + "(possibly empty but never <code>None</code>)")
   public NestedSet<Artifact> getLibraries() {
     NestedSetBuilder<Artifact> libs = NestedSetBuilder.linkOrder();
     CcLinkParamsProvider ccLinkParams = getInfo().get(CcLinkParamsProvider.CC_LINK_PARAMS);
@@ -74,9 +76,10 @@ public final class CcSkylarkApiProvider extends SkylarkApiProvider {
       name = "link_flags",
       structField = true,
       doc =
-          "Returns the immutable list of flags given to the C++ linker command for either "
-              + "FULLY STATIC mode (linkopts=[\"-static\"]) or MOSTLY STATIC mode (linkstatic=1) "
-              + "(possibly empty but never None)")
+          "Returns the list of flags given to the C++ linker command for either "
+              + "<code>FULLY STATIC</code> mode (<code>linkopts=[\"-static\"]</code>) or "
+              + "<code>MOSTLY STATIC</code> mode (<code>linkstatic=1</code>) "
+              + "(possibly empty but never <code>None</code>)")
   public ImmutableList<String> getLinkopts() {
     CcLinkParamsProvider ccLinkParams = getInfo().get(CcLinkParamsProvider.CC_LINK_PARAMS);
     if (ccLinkParams == null) {
@@ -89,8 +92,8 @@ public final class CcSkylarkApiProvider extends SkylarkApiProvider {
       name = "defines",
       structField = true,
       doc =
-          "Returns the immutable set of defines used to compile this target "
-              + "(possibly empty but never None).")
+          "Returns the list of defines used to compile this target "
+              + "(possibly empty but never <code>None</code>).")
   public ImmutableList<String> getDefines() {
     CppCompilationContext ccContext = getInfo().getProvider(CppCompilationContext.class);
     return ccContext == null ? ImmutableList.<String>of() : ccContext.getDefines();
@@ -100,8 +103,8 @@ public final class CcSkylarkApiProvider extends SkylarkApiProvider {
       name = "system_include_directories",
       structField = true,
       doc =
-          "Returns the immutable set of system include directories used to compile this target "
-              + "(possibly empty but never None).")
+          "Returns the list of system include directories used to compile this target "
+              + "(possibly empty but never <code>None</code>).")
   public ImmutableList<String> getSystemIncludeDirs() {
     CppCompilationContext ccContext = getInfo().getProvider(CppCompilationContext.class);
     if (ccContext == null) {
@@ -118,8 +121,8 @@ public final class CcSkylarkApiProvider extends SkylarkApiProvider {
       name = "include_directories",
       structField = true,
       doc =
-          "Returns the immutable set of include directories used to compile this target "
-              + "(possibly empty but never None).")
+          "Returns the list of include directories used to compile this target "
+              + "(possibly empty but never <code>None</code>).")
   public ImmutableList<String> getIncludeDirs() {
     CppCompilationContext ccContext = getInfo().getProvider(CppCompilationContext.class);
     if (ccContext == null) {
@@ -136,8 +139,8 @@ public final class CcSkylarkApiProvider extends SkylarkApiProvider {
       name = "quote_include_directories",
       structField = true,
       doc =
-          "Returns the immutable set of quote include directories used to compile this target "
-              + "(possibly empty but never None).")
+          "Returns the list of quote include directories used to compile this target "
+              + "(possibly empty but never <code>None</code>).")
   public ImmutableList<String> getQuoteIncludeDirs() {
     CppCompilationContext ccContext = getInfo().getProvider(CppCompilationContext.class);
     if (ccContext == null) {
@@ -154,8 +157,8 @@ public final class CcSkylarkApiProvider extends SkylarkApiProvider {
       name = "compile_flags",
       structField = true,
       doc =
-          "Returns the immutable set of flags used to compile this target "
-              + "(possibly empty but never None).")
+          "Returns the list of flags used to compile this target "
+              + "(possibly empty but never <code>None</code>).")
   public ImmutableList<String> getCcFlags() {
     CppCompilationContext ccContext = getInfo().getProvider(CppCompilationContext.class);
 
diff --git a/src/main/java/com/google/devtools/build/lib/rules/java/JavaSkylarkApiProvider.java b/src/main/java/com/google/devtools/build/lib/rules/java/JavaSkylarkApiProvider.java
index de7dc82b41..855ea6e4c3 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/java/JavaSkylarkApiProvider.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/java/JavaSkylarkApiProvider.java
@@ -38,7 +38,8 @@ import javax.annotation.Nullable;
   category = SkylarkModuleCategory.PROVIDER,
   doc =
       "Provides access to information about Java rules. Every Java-related target provides "
-          + "this struct, accessible as a 'java' field on a Target struct."
+          + "this struct, accessible as a <code>java</code> field on a "
+          + "<a href=\"Target.html\">target</a>."
 )
 public final class JavaSkylarkApiProvider extends SkylarkApiProvider {
   /** The name of the field in Skylark used to access this class. */
@@ -121,7 +122,7 @@ public final class JavaSkylarkApiProvider extends SkylarkApiProvider {
     name = "transitive_source_jars",
     doc =
         "Returns the Jars containing Java source files for the target and all of its transitive "
-            + "dependencies",
+            + "dependencies.",
     structField = true
   )
   public NestedSet<Artifact> getTransitiveSourceJars() {