Document source of truth for rctx.download* cache key

Documenting the default caching behaviour for `rctx.download` and `rctx.download_and_extract`.
 
Related to #22652

Closes #22716.

PiperOrigin-RevId: 653878029
Change-Id: I129f9eede2b841483a98d5335651c1d1198aaf76

src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkBaseExternalContext.java

@@ -632,7 +632,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",
             defaultValue = "False",
@@ -651,7 +654,8 @@ private StructImpl completeDownload(PendingDownload pendingDownload)
             named = true,
             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",
             defaultValue = "{}",
@@ -672,7 +676,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",
             defaultValue = "True",
@@ -852,7 +859,8 @@ public Object download(
             named = true,
             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",
             defaultValue = "{}",
@@ -873,7 +881,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",
             defaultValue = "{}",