Clean up/improve docs across several Apple classes.

PiperOrigin-RevId: 162676133

5 files changed, 198 insertions, 90 deletions

diff --git a/src/main/java/com/google/devtools/build/lib/rules/apple/AppleCommandLineOptions.java b/src/main/java/com/google/devtools/build/lib/rules/apple/AppleCommandLineOptions.java
index a3095e9bc3..3b13623b37 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/apple/AppleCommandLineOptions.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/apple/AppleCommandLineOptions.java
@@ -396,9 +396,12 @@ public class AppleCommandLineOptions extends FragmentOptions {
   @SkylarkModule(
     name = "apple_bitcode_mode",
     category = SkylarkModuleCategory.NONE,
-    doc =
-        "Apple Bitcode mode for compilation steps. Possible values are \"none\", "
-            + "\"embedded\", and \"embedded_markers\""
+    doc = "The Bitcode mode to use when compiling Objective-C and Swift code on Apple platforms. "
+        + "Possible values are:<br><ul>"
+        + "<li><code>'none'</code></li>"
+        + "<li><code>'embedded'</code></li>"
+        + "<li><code>'embedded_markers'</code></li>"
+        + "</ul>"
   )
   @Immutable
   public enum AppleBitcodeMode implements SkylarkValue {
@@ -472,7 +475,7 @@ public class AppleCommandLineOptions extends FragmentOptions {
     host.appleBitcodeMode = appleBitcodeMode;
     // The host apple platform type will always be MACOS, as no other apple platform type can
     // currently execute build actions. If that were the case, a host_apple_platform_type flag might
-    // be needed. 
+    // be needed.
     host.applePlatformType = PlatformType.MACOS;
 
     return host;
diff --git a/src/main/java/com/google/devtools/build/lib/rules/apple/AppleConfiguration.java b/src/main/java/com/google/devtools/build/lib/rules/apple/AppleConfiguration.java
index 4dd5b79f21..01c5879a22 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/apple/AppleConfiguration.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/apple/AppleConfiguration.java
@@ -163,7 +163,9 @@ public class AppleConfiguration extends BuildConfiguration.Fragment {
    * runtime OS supports them.
    */
   @SkylarkCallable(name = "ios_minimum_os", structField = true,
-      doc = "The minimum compatible iOS version for target simulators and devices.")
+      doc = "<b>Deprecated. Use <a href='#minimum_os_for_platform_type'>"
+          + "minimum_os_for_platform_type(apple_common.platform_type.ios)</a> instead.</b> "
+          + "The minimum compatible iOS version for target simulators and devices.")
   public DottedVersion getMinimumOs() {
     // TODO(bazel-team): Deprecate in favor of getMinimumOsForPlatformType(IOS).
     return iosMinimumOs;
@@ -205,7 +207,10 @@ public class AppleConfiguration extends BuildConfiguration.Fragment {
    * Returns the SDK version for a platform (whether they be for simulator or device). This is
    * directly derived from command line args.
    */
-  @SkylarkCallable(name = "sdk_version_for_platform", doc = "The SDK version given a platform.")
+  @SkylarkCallable(
+      name = "sdk_version_for_platform",
+      doc = "The version of the platform SDK that will be used to build targets for the given "
+          + "platform.")
   public DottedVersion getSdkVersionForPlatform(ApplePlatform platform) {
     switch (platform) {
       case IOS_DEVICE:
@@ -229,7 +234,11 @@ public class AppleConfiguration extends BuildConfiguration.Fragment {
    * of the {@code --xcode_version} build flag and the {@code xcode_config} target defined in the
    * {@code --xcode_version_config} flag. Returns null if no xcode is available.
    */
-  @SkylarkCallable(name = "xcode_version")
+  @SkylarkCallable(
+      name = "xcode_version",
+      doc = "Returns the Xcode version that is being used to build.<p>"
+          + "This will return <code>None</code> if no Xcode versions are available.",
+      allowReturnNones = true)
   @Nullable
   public DottedVersion getXcodeVersion() {
     return xcodeVersion;
@@ -240,7 +249,12 @@ public class AppleConfiguration extends BuildConfiguration.Fragment {
    * for actions pertaining to the given apple platform. Keys are variable names and values are
    * their corresponding values.
    */
-  @SkylarkCallable(name = "target_apple_env")
+  @SkylarkCallable(
+      name = "target_apple_env",
+      doc = "Returns a <code>dict</code> of environment variables that should be set for actions "
+          + "that build targets of the given Apple platform type. For example, this dictionary "
+          + "contains variables that denote the platform name and SDK version with which to "
+          + "build. The keys are variable names and the values are their corresponding values.")
   public ImmutableMap<String, String> getTargetAppleEnvironment(ApplePlatform platform) {
     ImmutableMap.Builder<String, String> mapBuilder = ImmutableMap.builder();
     mapBuilder.putAll(appleTargetPlatformEnv(platform));
@@ -254,11 +268,10 @@ public class AppleConfiguration extends BuildConfiguration.Fragment {
    */
   @SkylarkCallable(
       name = "apple_host_system_env",
-      doc =
-          "Returns a map of environment variables that should be propagated for actions that "
-          + "build on an apple host system. These environment variables are needed by the apple "
-          + "toolchain. Keys are variable names and values are their corresponding values."
-    )
+      doc = "Returns a <a href='dict.html'>dict</a> of environment variables that should be set "
+          + "for actions that need to run build tools on an Apple host system, such as the version "
+          + "of Xcode that should be used. The keys are variable names and the values are their "
+          + "corresponding values.")
   public ImmutableMap<String, String> getAppleHostSystemEnv() {
     DottedVersion xcodeVersion = getXcodeVersion();
     if (xcodeVersion != null) {
@@ -299,7 +312,10 @@ public class AppleConfiguration extends BuildConfiguration.Fragment {
    * platform or cpu for all actions spawned in this configuration; it is appropriate for
    * identifying the target cpu of iOS compile and link actions within this configuration.
    */
-  @SkylarkCallable(name = "ios_cpu", doc = "The value of ios_cpu for this configuration.")
+  @SkylarkCallable(
+      name = "ios_cpu",
+      doc = "<b>Deprecated. Use <a href='#single_arch_cpu'>single_arch_cpu</a> instead.</b> "
+          + "The value of ios_cpu for this configuration.")
   public String getIosCpu() {
     return iosCpu;
   }
@@ -325,9 +341,10 @@ public class AppleConfiguration extends BuildConfiguration.Fragment {
     name = "single_arch_cpu",
     structField = true,
     doc =
-        "The single \"effective\" architecture for this configuration (e.g. i386 or arm64) "
-            + "in the context of rule logic which is only concerned with a single architecture "
-            + "(such as in objc_library, which registers single-architecture compile actions). "
+        "The single \"effective\" architecture for this configuration (e.g., <code>i386</code> or "
+            + "<code>arm64</code>) in the context of rule logic that is only concerned with a "
+            + "single architecture (such as <code>objc_library</code>, which registers "
+            + "single-architecture compile actions)."
   )
   public String getSingleArchitecture() {
     if (!Strings.isNullOrEmpty(appleSplitCpu)) {
@@ -346,17 +363,17 @@ public class AppleConfiguration extends BuildConfiguration.Fragment {
         return tvosCpus.get(0);
       case MACOS:
         return macosCpus.get(0);
-      default: 
+      default:
         throw new IllegalArgumentException("Unhandled platform type " + applePlatformType);
     }
   }
- 
+
   /**
    * Gets the "effective" architecture(s) for the given {@link PlatformType}. For example,
    * "i386" or "arm64". At least one architecture is always returned. Prefer this over
    * {@link #getSingleArchitecture} in rule logic which may support multiple architectures, such
    * as bundling rules.
-   * 
+   *
    * <p>Effective architecture(s) is determined using the following rules:
    * <ol>
    * <li>If {@code --apple_split_cpu} is set (done via prior configuration transition), then
@@ -365,7 +382,7 @@ public class AppleConfiguration extends BuildConfiguration.Fragment {
    * all architectures from that flag.</li>
    * <li>In the case of iOS, use {@code --ios_cpu} for backwards compatibility.</li>
    * <li>Use the default.</li></ol>
-   * 
+   *
    * @throws IllegalArgumentException if {@code --apple_platform_type} is set (via prior
    *     configuration transition) yet does not match {@code platformType}
    */
@@ -391,7 +408,7 @@ public class AppleConfiguration extends BuildConfiguration.Fragment {
         return tvosCpus;
       case MACOS:
         return macosCpus;
-      default: 
+      default:
         throw new IllegalArgumentException("Unhandled platform type " + platformType);
     }
   }
@@ -404,10 +421,9 @@ public class AppleConfiguration extends BuildConfiguration.Fragment {
    */
   @SkylarkCallable(
     name = "single_arch_platform",
-    doc =
-        "The platform of the current configuration. This should only be invoked in a context where "
-            + "only a single architecture may be supported; consider mutli_arch_platform for other "
-            + "cases.",
+    doc = "The platform of the current configuration. This should only be invoked in a context "
+        + "where only a single architecture may be supported; consider "
+        + "<a href='#multi_arch_platform'>mutli_arch_platform</a> for other cases.",
     structField = true
   )
   public ApplePlatform getSingleArchPlatform() {
@@ -424,10 +440,9 @@ public class AppleConfiguration extends BuildConfiguration.Fragment {
   // TODO(bazel-team): This should support returning multiple platforms.
   @SkylarkCallable(
     name = "multi_arch_platform",
-    doc =
-        "The platform of the current configuration "
-            + "for the given platform type. This should only be invoked in a context where multiple"
-            + " architectures may be supported; consider single_arch_platform for other cases."
+    doc = "The platform of the current configuration for the given platform type. This should only "
+        + "be invoked in a context where multiple architectures may be supported; consider "
+        + "<a href='#single_arch_platform'>single_arch_platform</a> for other cases."
   )
   public ApplePlatform getMultiArchPlatform(PlatformType platformType) {
     List<String> architectures = getMultiArchitectures(platformType);
@@ -469,7 +484,11 @@ public class AppleConfiguration extends BuildConfiguration.Fragment {
    * #getMultiArchPlatform(PlatformType)}.
    */
   // TODO(b/28754442): Deprecate for more general skylark-exposed platform retrieval.
-  @SkylarkCallable(name = "ios_cpu_platform", doc = "The platform given by the ios_cpu flag.")
+  @SkylarkCallable(
+      name = "ios_cpu_platform",
+      doc = "<b>Deprecated. Use <a href='#single_arch_platform'>single_arch_platform</a> or "
+          + "<a href='#multi_arch_platform'>multi_arch_platform</a> instead.</b> "
+          + "The platform given by the ios_cpu flag.")
   public ApplePlatform getIosCpuPlatform() {
     return ApplePlatform.forTarget(PlatformType.IOS, iosCpu);
   }
@@ -489,7 +508,7 @@ public class AppleConfiguration extends BuildConfiguration.Fragment {
     }
     return getIosCpu();
   }
-  
+
   /**
    * List of all CPUs that this invocation is being built for. Different from {@link #getIosCpu()}
    * which is the specific CPU <b>this target</b> is being built for.
@@ -518,7 +537,9 @@ public class AppleConfiguration extends BuildConfiguration.Fragment {
    */
   @SkylarkCallable(
     name = "bitcode_mode",
-    doc = "Returns the bitcode mode to use for compilation steps.",
+    doc = "Returns the Bitcode mode to use for compilation steps.<p>"
+        + "This field is only valid for device builds; for simulator builds, it always returns "
+        + "<code>'none'</code>.",
     structField = true
   )
   public AppleBitcodeMode getBitcodeMode() {
@@ -586,7 +607,8 @@ public class AppleConfiguration extends BuildConfiguration.Fragment {
   /** Returns the identifier for an Xcode toolchain to use with tools. */
   @SkylarkCallable(
     name = "xcode_toolchain",
-    doc = "Identifier for the custom Xcode toolchain to use in build or None if not specified.",
+    doc = "Identifier for the custom Xcode toolchain to use in build, or <code>None</code> if it "
+        + "is not specified.",
     allowReturnNones = true,
     structField = true
   )
diff --git a/src/main/java/com/google/devtools/build/lib/rules/apple/ApplePlatform.java b/src/main/java/com/google/devtools/build/lib/rules/apple/ApplePlatform.java
index d81e698d6b..1e0ba56d08 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/apple/ApplePlatform.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/apple/ApplePlatform.java
@@ -33,7 +33,29 @@ import javax.annotation.Nullable;
 @SkylarkModule(
   name = "platform",
   category = SkylarkModuleCategory.NONE,
-  doc = "Distinguishes between various apple platforms."
+  doc = "Corresponds to Xcode's notion of a platform as would be found in "
+      + "<code>Xcode.app/Contents/Developer/Platforms</code>. Each platform represents an Apple "
+      + "platform type (such as iOS or tvOS) combined with one or more related CPU "
+      + "architectures. For example, the iOS simulator platform supports <code>x86_64</code> and "
+      + "<code>i386</code> architectures.<p>"
+      + "Specific instances of this type can be retrieved from the fields of the "
+      + "<a href='apple_common.html#platform'>apple_common.platform</a> struct:<br><ul>"
+      + "<li><code>apple_common.platform.ios_device</code></li>"
+      + "<li><code>apple_common.platform.ios_simulator</code></li>"
+      + "<li><code>apple_common.platform.macos</code></li>"
+      + "<li><code>apple_common.platform.tvos_device</code></li>"
+      + "<li><code>apple_common.platform.tvos_simulator</code></li>"
+      + "<li><code>apple_common.platform.watchos_device</code></li>"
+      + "<li><code>apple_common.platform.watchos_simulator</code></li>"
+      + "</ul><p>"
+      + "More commonly, however, the <a href='apple.html'>apple</a> configuration fragment has "
+      + "fields/methods that allow rules to determine the platform for which a target is being "
+      + "built.<p>"
+      + "Example:<br>"
+      + "<pre class='language-python'>\n"
+      + "p = apple_common.platform.ios_device\n"
+      + "print(p.name_in_plist)  # 'iPhoneOS'\n"
+      + "</pre>"
 )
 @Immutable
 public enum ApplePlatform implements SkylarkValue {
@@ -88,8 +110,8 @@ public enum ApplePlatform implements SkylarkValue {
    */
   @SkylarkCallable(
     name = "is_device",
-    doc = "Returns true if this platform is a device platform, or false if it is a simulator "
-        + "platform.",
+    doc = "Returns <code>True</code> if this platform is a device platform or <code>False</code> "
+        + "if it is a simulator platform.",
     structField = true
   )
   public boolean isDevice() {
@@ -101,9 +123,12 @@ public enum ApplePlatform implements SkylarkValue {
    * setting.
    */
   @SkylarkCallable(name = "name_in_plist", structField = true,
-    doc = "The name of the platform as it appears in the CFBundleSupportedPlatforms plist "
-        + "setting. This name can also be converted to lowercase and passed to command-line "
-        + "tools, such as ibtool and actool.")
+    doc = "The name of the platform as it appears in the <code>CFBundleSupportedPlatforms</code> "
+        + "entry of an Info.plist file and in Xcode's platforms directory, without the extension "
+        + "(for example, <code>iPhoneOS</code> or <code>iPhoneSimulator</code>).<br>"
+        + "This name, when converted to lowercase (e.g., <code>iphoneos</code>, "
+        + "<code>iphonesimulator</code>), can be passed to Xcode's command-line tools like "
+        + "<code>ibtool</code> and <code>actool</code> when they expect a platform name.")
   public String getNameInPlist() {
     return nameInPlist;
   }
@@ -172,7 +197,7 @@ public enum ApplePlatform implements SkylarkValue {
   public static ApplePlatform forTargetCpu(String targetCpu) {
     ApplePlatform platform = forTargetCpuNullable(targetCpu);
     if (platform != null) {
-      return platform; 
+      return platform;
     } else {
       throw new IllegalArgumentException(
           "No supported apple platform registered for target cpu " + targetCpu);
@@ -211,7 +236,20 @@ public enum ApplePlatform implements SkylarkValue {
   @SkylarkModule(
     name = "platform_type",
     category = SkylarkModuleCategory.NONE,
-    doc = "Describes Apple platform \"type\", such as iOS, tvOS, macOS etc."
+    doc = "Describes an Apple \"platform type\", such as iOS, macOS, tvOS, or watchOS. This is "
+        + "distinct from a \"platform\", which is the platform type combined with one or more CPU "
+        + "architectures.<p>"
+        + "Specific instances of this type can be retrieved by accessing the fields of the "
+        + "<a href='apple_common.html#platform_type'>apple_common.platform_type</a>:<br><ul>"
+        + "<li><code>apple_common.platform_type.ios</code></li>"
+        + "<li><code>apple_common.platform_type.macos</code></li>"
+        + "<li><code>apple_common.platform_type.tvos</code></li>"
+        + "<li><code>apple_common.platform_type.watchos</code></li>"
+        + "</ul><p>"
+        + "Likewise, the platform type of an existing platform value can be retrieved using its "
+        + "<code>platform_type</code> field.<p>"
+        + "Platform types can be converted to a lowercase string (e.g., <code>ios</code> or "
+        + "<code>macos</code>) using the <a href='globals.html#str'>str</a> function."
   )
   @Immutable
   public enum PlatformType implements SkylarkValue {
@@ -234,10 +272,10 @@ public enum ApplePlatform implements SkylarkValue {
     public String toString() {
       return name().toLowerCase();
     }
-    
+
     /**
      * Returns the {@link PlatformType} with given name (case insensitive).
-     * 
+     *
      * @throws IllegalArgumentException if the name does not match a valid platform type.
      */
     public static PlatformType fromString(String name) {
diff --git a/src/main/java/com/google/devtools/build/lib/rules/apple/swift/SwiftConfiguration.java b/src/main/java/com/google/devtools/build/lib/rules/apple/swift/SwiftConfiguration.java
index f10c0e4632..4636f1eb60 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/apple/swift/SwiftConfiguration.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/apple/swift/SwiftConfiguration.java
@@ -50,14 +50,18 @@ public class SwiftConfiguration extends BuildConfiguration.Fragment {
   /** Returns whether to enable Whole Module Optimization. */
   @SkylarkCallable(
     name = "enable_whole_module_optimization",
-    doc = "Whether to enable Whole Module Optimization."
+    doc = "<code>True</code> if <em>whole module optimization</em> should be enabled when "
+        + "compiling Swift code; otherwise, <code>False</code>."
   )
   public boolean enableWholeModuleOptimization() {
     return enableWholeModuleOptimization;
   }
 
   /** Returns a list of options to use for compiling Swift. */
-  @SkylarkCallable(name = "copts", doc = "Returns a list of options to use for compiling Swift.")
+  @SkylarkCallable(
+    name = "copts",
+    doc = "A list of compiler options that should be passed to <code>swiftc</code> when compiling "
+        + "Swift code.")
   public ImmutableList<String> getCopts() {
     return copts;
   }
diff --git a/src/main/java/com/google/devtools/build/lib/rules/objc/AppleSkylarkCommon.java b/src/main/java/com/google/devtools/build/lib/rules/objc/AppleSkylarkCommon.java
index f4351001cc..7f5820b3f5 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/objc/AppleSkylarkCommon.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/objc/AppleSkylarkCommon.java
@@ -88,11 +88,20 @@ public class AppleSkylarkCommon {
 
   @SkylarkCallable(
     name = "platform_type",
-    doc = "Returns a struct containing fields corresponding to Apple platform types: 'ios', "
-        + "'watchos', 'tvos', and 'macos'. These values can be passed to methods that expect a "
-        + "platform type, like the 'apple' configuration fragment's 'multi_arch_platform' "
-        + "method. For example, ctx.fragments.apple.multi_arch_platform(apple_common."
-        + "platform_type.ios).",
+    doc = "An enum-like struct that contains the following fields corresponding to Apple platform "
+        + "types:<br><ul>"
+        + "<li><code>ios</code></li>"
+        + "<li><code>macos</code></li>"
+        + "<li><code>tvos</code></li>"
+        + "<li><code>watchos</code></li>"
+        + "</ul><p>"
+        + "These values can be passed to methods that expect a platform type, like the 'apple' "
+        + "configuration fragment's "
+        + "<a href='apple.html#multi_arch_platform'>multi_arch_platform</a> method.<p>"
+        + "Example:<p>"
+        + "<pre class='language-python'>\n"
+        + "ctx.fragments.apple.multi_arch_platform(apple_common.platform_type.ios)\n"
+        + "</pre>",
     structField = true
   )
   public SkylarkClassObject getPlatformTypeStruct() {
@@ -104,10 +113,18 @@ public class AppleSkylarkCommon {
 
   @SkylarkCallable(
       name = "platform",
-      doc = "Returns a struct containing fields corresponding to Apple platforms. These values "
-          + "can be passed to methods that expect a platform, like the 'apple' configuration "
-          + "fragment's 'sdk_version_for_platform' method. Each platform_type except for macosx "
-          + "has two platform types -- one for device, and one for simulator.",
+      doc = "An enum-like struct that contains the following fields corresponding to Apple "
+          + "platforms:<br><ul>"
+          + "<li><code>ios_device</code></li>"
+          + "<li><code>ios_simulator</code></li>"
+          + "<li><code>macos</code></li>"
+          + "<li><code>tvos_device</code></li>"
+          + "<li><code>tvos_simulator</code></li>"
+          + "<li><code>watchos_device</code></li>"
+          + "<li><code>watchos_device</code></li>"
+          + "</ul><p>"
+          + "These values can be passed to methods that expect a platform, like "
+          + "<a href='apple.html#sdk_version_for_platform'>apple.sdk_version_for_platform</a>.",
       structField = true
   )
   public SkylarkClassObject getPlatformStruct() {
@@ -119,9 +136,13 @@ public class AppleSkylarkCommon {
 
   @SkylarkCallable(
     name = XcodeVersionProperties.SKYLARK_NAME,
-    doc =
-        "Returns the provider constructor for XcodeVersionProperties. If a target propagates "
-            + "the XcodeVersionProperties provider, use this as the key with which to retrieve it.",
+    doc = "The constructor/key for the <code>XcodeVersionProperties</code> provider.<p>"
+        + "If a target propagates the <code>XcodeVersionProperties</code> provider, use this as "
+        + "the key with which to retrieve it. Example:<br>"
+        + "<pre class='language-python'>\n"
+        + "dep = ctx.attr.deps[0]\n"
+        + "p = dep[apple_common.XcodeVersionProperties]\n"
+        + "</pre>",
     structField = true
   )
   public ClassObjectConstructor getXcodeVersionPropertiesConstructor() {
@@ -133,7 +154,7 @@ public class AppleSkylarkCommon {
     // a migration of existing skylark rules.
     name = "Objc",
     doc = "The constructor/key for the <code>Objc</code> provider.<p>"
-        + "If a target propagates the <code>Objc</code> provider, use this as the"
+        + "If a target propagates the <code>Objc</code> provider, use this as the "
         + "key with which to retrieve it. Example:<br>"
         + "<pre class='language-python'>\n"
         + "dep = ctx.attr.deps[0]\n"
@@ -147,10 +168,13 @@ public class AppleSkylarkCommon {
 
   @SkylarkCallable(
     name = AppleDynamicFrameworkProvider.SKYLARK_NAME,
-    doc =
-        "Returns the provider constructor for AppleDynamicFramework. If a target propagates "
-            + "the AppleDynamicFramework provider, use this as the key with which to retrieve "
-            + "it.",
+    doc = "The constructor/key for the <code>AppleDynamicFramework</code> provider.<p>"
+        + "If a target propagates the <code>AppleDynamicFramework</code> provider, use this as the "
+        + "key with which to retrieve it. Example:<br>"
+        + "<pre class='language-python'>\n"
+        + "dep = ctx.attr.deps[0]\n"
+        + "p = dep[apple_common.AppleDynamicFramework]\n"
+        + "</pre>",
     structField = true
   )
   public ClassObjectConstructor getAppleDynamicFrameworkConstructor() {
@@ -159,9 +183,13 @@ public class AppleSkylarkCommon {
 
   @SkylarkCallable(
     name = AppleDylibBinaryProvider.SKYLARK_NAME,
-    doc =
-        "Returns the provider constructor for AppleDylibBinary. If a target propagates "
-            + "the AppleDylibBinary provider, use this as the key with which to retrieve it.",
+    doc = "The constructor/key for the <code>AppleDylibBinary</code> provider.<p>"
+        + "If a target propagates the <code>AppleDylibBinary</code> provider, use this as the "
+        + "key with which to retrieve it. Example:<br>"
+        + "<pre class='language-python'>\n"
+        + "dep = ctx.attr.deps[0]\n"
+        + "p = dep[apple_common.AppleDylibBinary]\n"
+        + "</pre>",
     structField = true
   )
   public ClassObjectConstructor getAppleDylibBinaryConstructor() {
@@ -170,9 +198,13 @@ public class AppleSkylarkCommon {
 
   @SkylarkCallable(
     name = AppleExecutableBinaryProvider.SKYLARK_NAME,
-    doc =
-        "Returns the provider constructor for AppleExecutableBinary. If a target propagates "
-            + "the AppleExecutableBinary provider, use this as the key with which to retrieve it.",
+    doc = "The constructor/key for the <code>AppleExecutableBinary</code> provider.<p>"
+        + "If a target propagates the <code>AppleExecutableBinary</code> provider, use this as the "
+        + "key with which to retrieve it. Example:<br>"
+        + "<pre class='language-python'>\n"
+        + "dep = ctx.attr.deps[0]\n"
+        + "p = dep[apple_common.AppleExecutableBinary]\n"
+        + "</pre>",
     structField = true
   )
   public ClassObjectConstructor getAppleExecutableBinaryConstructor() {
@@ -180,22 +212,29 @@ public class AppleSkylarkCommon {
   }
 
   @SkylarkCallable(
-      name = AppleStaticLibraryProvider.SKYLARK_NAME,
-      doc =
-          "Returns the provider constructor for AppleStaticLibrary. If a target propagates "
-              + "the AppleStaticLibrary provider, use this as the key with which to retrieve it.",
-      structField = true
-    )
-    public ClassObjectConstructor getAppleStaticLibraryProvider() {
-      return AppleStaticLibraryProvider.SKYLARK_CONSTRUCTOR;
-    }
+    name = AppleStaticLibraryProvider.SKYLARK_NAME,
+    doc = "The constructor/key for the <code>AppleStaticLibrary</code> provider.<p>"
+        + "If a target propagates the <code>AppleStaticLibrary</code> provider, use this as the "
+        + "key with which to retrieve it. Example:<br>"
+        + "<pre class='language-python'>\n"
+        + "dep = ctx.attr.deps[0]\n"
+        + "p = dep[apple_common.AppleStaticLibrary]\n"
+        + "</pre>",
+    structField = true
+  )
+  public ClassObjectConstructor getAppleStaticLibraryProvider() {
+    return AppleStaticLibraryProvider.SKYLARK_CONSTRUCTOR;
+  }
 
   @SkylarkCallable(
     name = AppleDebugOutputsProvider.SKYLARK_NAME,
-    doc =
-        "Returns the provider constructor for AppleDebugOutputsProvider. If a target propagates "
-            + "the AppleDebugOutputsProvider provider, use this as the key with which to retrieve "
-            + "it.",
+    doc = "The constructor/key for the <code>AppleDebugOutputs</code> provider.<p>"
+        + "If a target propagates the <code>AppleDebugOutputs</code> provider, use this as the "
+        + "key with which to retrieve it. Example:<br>"
+        + "<pre class='language-python'>\n"
+        + "dep = ctx.attr.deps[0]\n"
+        + "p = dep[apple_common.AppleDebugOutputs]\n"
+        + "</pre>",
     structField = true
   )
   public ClassObjectConstructor getAppleDebugOutputsConstructor() {
@@ -204,10 +243,13 @@ public class AppleSkylarkCommon {
 
   @SkylarkCallable(
     name = AppleLoadableBundleBinaryProvider.SKYLARK_NAME,
-    doc =
-        "Returns the provider constructor for AppleLoadableBundleBinaryProvider. If a target "
-            + "propagates the AppleLoadableBundleBinaryProvider provider, use this as the key "
-            + "with which to retrieve it.",
+    doc = "The constructor/key for the <code>AppleLoadableBundleBinary</code> provider.<p>"
+        + "If a target propagates the <code>AppleLoadableBundleBinary</code> provider, use this as "
+        + "the key with which to retrieve it. Example:<br>"
+        + "<pre class='language-python'>\n"
+        + "dep = ctx.attr.deps[0]\n"
+        + "p = dep[apple_common.AppleLoadableBundleBinary]\n"
+        + "</pre>",
     structField = true
   )
   public ClassObjectConstructor getAppleLoadableBundleBinaryConstructor() {
@@ -216,10 +258,9 @@ public class AppleSkylarkCommon {
 
   @SkylarkCallable(
     name = IosDeviceProvider.SKYLARK_NAME,
-    doc =
-        "[NOTE: This is deprecated and will be removed in the future. Use the new Skylark testing "
-            + "rules instead.] Returns the provider constructor for IosDeviceProvider. Use this as "
-            + "a key to access the attributes exposed by ios_device.",
+    doc = "<b>Deprecated. Use the new Skylark testing rules instead.</b> Returns the provider "
+        + "constructor for IosDeviceProvider. Use this as a key to access the attributes exposed "
+        + "by ios_device.",
     structField = true
   )
   public ClassObjectConstructor getIosDeviceProviderConstructor() {