utils.bzl: improve doc strings

...to specify more precisely the assumptions and intended
use for those functions.

Fixes #7913.

Change-Id: I067490b21a3092f70673b0db12ba884b31924e13
PiperOrigin-RevId: 241537153

tools/build_defs/repo/utils.bzl

@@ -31,9 +31,11 @@ load(
 def workspace_and_buildfile(ctx):
     """Utility function for writing WORKSPACE and, if requested, a BUILD file.
 
-    It assumes the parameters name, build_file, build_file_contents,
-    workspace_file, and workspace_file_content to be
-    present in ctx.attr, the latter four possibly with value None.
+    This rule is inteded to be used in the implementation function of a
+    repository rule.
+    It assumes the parameters `name`, `build_file`, `build_file_contents`,
+    `workspace_file`, and `workspace_file_content` to be
+    present in `ctx.attr`, the latter four possibly with value None.
 
     Args:
       ctx: The repository context of the repository rule calling this utility
@@ -66,7 +68,16 @@ def workspace_and_buildfile(ctx):
         ctx.file("BUILD.bazel", ctx.attr.build_file_content)
 
 def patch(ctx):
-    """Implementation of patching an already extracted repository"""
+    """Implementation of patching an already extracted repository.
+
+    This rule is inteded to be used in the implementation function of a
+    repository rule. It assuumes that the parameters `patches`, `patchtool`,
+    `patch_args`, and `patch_cmds` are present in `ctx.attr`.
+
+    Args:
+      ctx: The repository context of the repository rule calling this utility
+        function.
+    """
     bash_exe = ctx.os.environ["BAZEL_SH"] if "BAZEL_SH" in ctx.os.environ else "bash"
     if len(ctx.attr.patches) > 0 or len(ctx.attr.patch_cmds) > 0:
         ctx.report_progress("Patching repository")