diff --git a/src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkBaseExternalContext.java b/src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkBaseExternalContext.java
index fda4fac76a9f65..5df934f7e1fd96 100644
--- a/src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkBaseExternalContext.java
+++ b/src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkBaseExternalContext.java
@@ -637,7 +637,10 @@ private StructImpl completeDownload(PendingDownload pendingDownload)
                 This must match the SHA-256 hash of the file downloaded. It is a security \
                 risk to omit the SHA-256 as remote files can change. At best omitting this \
                 field will make your build non-hermetic. It is optional to make development \
-                easier but should be set before shipping.
+                easier but should be set before shipping. \
+                If provided, the repository cache will first be checked for a file with the \
+                given hash; a download will only be attempted if the file was not found in \
+                the cache. After a successful download, the file will be added to the cache.
                 """),
         @Param(
             name = "executable",
@@ -660,7 +663,8 @@ private StructImpl completeDownload(PendingDownload pendingDownload)
             doc =
                 """
                 If set, restrict cache hits to those cases where the file was added to the cache \
-                with the same canonical id.
+                with the same canonical id. By default caching uses the checksum \
+                (<code>sha256</code> or <code>integrity</code>).
                 """),
         @Param(
             name = "auth",
@@ -683,7 +687,10 @@ private StructImpl completeDownload(PendingDownload pendingDownload)
                 This must match the checksum of the file downloaded. It is a security \
                 risk to omit the checksum as remote files can change. At best omitting this \
                 field will make your build non-hermetic. It is optional to make development \
-                easier but should be set before shipping.
+                easier but should be set before shipping. \
+                If provided, the repository cache will first be checked for a file with the \
+                given checksum; a download will only be attempted if the file was not found in \
+                the cache. After a successful download, the file will be added to the cache.
                 """),
         @Param(
             name = "block",
@@ -879,7 +886,8 @@ public Object download(
             doc =
                 """
                 If set, restrict cache hits to those cases where the file was added to the cache \
-                with the same canonical id.
+                with the same canonical id. By default caching uses the checksum"
+                (<code>sha256</code> or <code>integrity</code>).
                 """),
         @Param(
             name = "auth",
@@ -902,7 +910,10 @@ public Object download(
                 This must match the checksum of the file downloaded. It is a security \
                 risk to omit the checksum as remote files can change. At best omitting this \
                 field will make your build non-hermetic. It is optional to make development \
-                easier but should be set before shipping.
+                easier but should be set before shipping. \
+                If provided, the repository cache will first be checked for a file with the \
+                given checksum; a download will only be attempted if the file was not found in \
+                the cache. After a successful download, the file will be added to the cache. \
                 """),
         @Param(
             name = "rename_files",