Normalize repository starlark API docs

Now that Bazel built with JDK21, Starlark builtin documentation can be made more readable in source (and easier to author, since less escaping is required).

This PR refactors the repository starlark API under `src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/` to use multi-line text blocks. Minor edits have also been made to some documentation (replacing unprocessed back-ticks with HTML `code` tags, adding `code` tags where I think it makes sense, capitalization, punctuation).

Stats wise (excluding `test` directory) this covers;
- 34 of 1101 `@StarlarkMethod(...)` (5 of 170 files)
- 5 of 233 `@StarlarkBuiltin(...)` (5 of 221 files)

Closes bazelbuild#22762.

PiperOrigin-RevId: 650649974
Change-Id: I3002b8d4bccbe1d11aa6aff184b448eb1f280ba4

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

@@ -50,9 +50,11 @@
  name = "exec_result",
  category = DocCategory.BUILTIN,
  doc =
- "A structure storing result of repository_ctx.execute() method. It contains the standard"
- + " output stream content, the standard error stream content and the execution return"
- + " code.")
+ """
+ A structure storing result of repository_ctx.execute() method. It contains the standard \
+ output stream content, the standard error stream content and the execution return \
+ code.
+ """)
 final class StarlarkExecutionResult implements StarlarkValue {
  private final int returnCode;
  private final String stdout;
@@ -73,9 +75,11 @@ public boolean isImmutable() {
  name = "return_code",
  structField = true,
  doc =
- "The return code returned after the execution of the program. 256 if the process was"
- + " terminated by a time out; values larger than 128 indicate termination by a"
- + " signal.")
+ """
+ The return code returned after the execution of the program. 256 if the process was \
+ terminated by a time out; values larger than 128 indicate termination by a \
+ signal.
+ """)
  public int getReturnCode() {
  return returnCode;
  }

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

@@ -46,12 +46,14 @@ public boolean isImmutable() {
  name = "environ",
  structField = true,
  doc =
- "The dictionary of environment variables."
- + "<p><b>NOTE</b>: Retrieving an environment variable from this dictionary does not "
- + "establish a dependency from a repository rule or module extension to the "
- + "environment variable. To establish a dependency when looking up an "
- + "environment variable, use either <code>repository_ctx.getenv</code> or "
- + "<code>module_ctx.getenv</code> instead.")
+ """
+ The dictionary of environment variables. \
+ <p><b>NOTE</b>: Retrieving an environment variable from this dictionary does not \
+ establish a dependency from a repository rule or module extension to the \
+ environment variable. To establish a dependency when looking up an \
+ environment variable, use either <code>repository_ctx.getenv</code> or \
+ <code>module_ctx.getenv</code> instead.
+ """)
  public ImmutableMap<String, String> getEnvironmentVariables() {
  return environ;
  }
@@ -60,8 +62,10 @@ public ImmutableMap<String, String> getEnvironmentVariables() {
  name = "name",
  structField = true,
  doc =
- "A string identifying the operating system Bazel is running on (the value of the"
- + " \"os.name\" Java property converted to lower case).")
+ """
+ A string identifying the operating system Bazel is running on (the value of the \
+ <code>"os.name"</code> Java property converted to lower case).
+ """)
  public String getName() {
  return System.getProperty("os.name").toLowerCase(Locale.ROOT);
  }
@@ -70,8 +74,10 @@ public String getName() {
  name = "arch",
  structField = true,
  doc =
- "A string identifying the architecture Bazel is running on (the value of the \"os.arch\""
- + " Java property converted to lower case).")
+ """
+ A string identifying the architecture Bazel is running on (the value of the \
+ <code>"os.arch"</code> Java property converted to lower case).
+ """)
  public String getArch() {
  return System.getProperty("os.arch").toLowerCase(Locale.ROOT);
  }

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

@@ -84,24 +84,27 @@ public String getBasename() {
  @StarlarkMethod(
  name = "readdir",
  doc =
- "Returns the list of entries in the directory denoted by this path. Each entry is a "
- + "<code>path</code> object itself.",
+ """
+ Returns the list of entries in the directory denoted by this path. Each entry is a \
+ <code>path</code> object itself.
+ """,
  parameters = {
  @Param(
  name = "watch",
  defaultValue = "'auto'",
  positional = false,
  named = true,
  doc =
- "whether Bazel should watch the list of entries in this directory and refetch the "
- + "repository or re-evaluate the module extension next time when any changes "
- + "are detected. Changes to detect include entry creation, deletion, and "
- + "renaming. Note that this doesn't watch the <em>contents</em> of any entries "
- + "in the directory.<p>Can be the string 'yes', 'no', or 'auto'. If set to "
- + "'auto', Bazel will only watch this directory when it is legal to do so (see "
- + "<a "
- + "href=\"repository_ctx.html#watch\"><code>repository_ctx.watch()</code></a> "
- + "docs for more information)."),
+ """
+ whether Bazel should watch the list of entries in this directory and refetch the \
+ repository or re-evaluate the module extension next time when any changes \
+ are detected. Changes to detect include entry creation, deletion, and \
+ renaming. Note that this doesn't watch the <em>contents</em> of any entries \
+ in the directory.<p>Can be the string 'yes', 'no', or 'auto'. If set to \
+ 'auto', Bazel will only watch this directory when it is legal to do so (see \
+ <a href="repository_ctx.html#watch"><code>repository_ctx.watch()</code></a> \
+ docs for more information).
+ """),
  })
  public ImmutableList<StarlarkPath> readdir(String watch)
  throws EvalException, RepositoryFunctionException, InterruptedException {
@@ -138,8 +141,10 @@ public StarlarkPath getDirname() {
  @Param(
  name = "relative_paths",
  doc =
- "Zero or more relative path strings to append to this path with path separators"
- + "added as needed."))
+ """
+ Zero or more relative path strings to append to this path with path separators \
+ added as needed.
+ """))
  public StarlarkPath getChild(Tuple relativePaths) throws EvalException {
  return new StarlarkPath(
  ctx,
@@ -153,10 +158,12 @@ public StarlarkPath getChild(Tuple relativePaths) throws EvalException {
  name = "exists",
  structField = true,
  doc =
- "Returns true if the file or directory denoted by this path exists.<p>Note that "
- + "accessing this field does <em>not</em> cause the path to be watched. If you'd "
- + "like the repo rule or module extension to be sensitive to the path's existence, "
- + "use the <code>watch()</code> method on the context object.")
+ """
+ Returns true if the file or directory denoted by this path exists.<p>Note that \
+ accessing this field does <em>not</em> cause the path to be watched. If you'd \
+ like the repo rule or module extension to be sensitive to the path's existence, \
+ use the <code>watch()</code> method on the context object.
+ """)
  public boolean exists() {
  return path.exists();
  }
@@ -165,10 +172,12 @@ public boolean exists() {
  name = "is_dir",
  structField = true,
  doc =
- "Returns true if this path points to a directory.<p>Note that accessing this field does "
- + "<em>not</em> cause the path to be watched. If you'd like the repo rule or module "
- + "extension to be sensitive to whether the path is a directory or a file, use the "
- + "<code>watch()</code> method on the context object.")
+ """
+ Returns true if this path points to a directory.<p>Note that accessing this field does \
+ <em>not</em> cause the path to be watched. If you'd like the repo rule or module \
+ extension to be sensitive to whether the path is a directory or a file, use the \
+ <code>watch()</code> method on the context object.
+ """)
  public boolean isDir() {
  return path.isDirectory();
  }
@@ -177,8 +186,10 @@ public boolean isDir() {
  name = "realpath",
  structField = true,
  doc =
- "Returns the canonical path for this path by repeatedly replacing all symbolic links "
- + "with their referents.")
+ """
+ Returns the canonical path for this path by repeatedly replacing all symbolic links \
+ with their referents.
+ """)
  public StarlarkPath realpath() throws IOException {
  return new StarlarkPath(ctx, path.resolveSymbolicLinks());
  }

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

@@ -69,10 +69,12 @@
  name = "repository_ctx",
  category = DocCategory.BUILTIN,
  doc =
- "The context of the repository rule containing"
- + " helper functions and information about attributes. You get a repository_ctx object"
- + " as an argument to the <code>implementation</code> function when you create a"
- + " repository rule.")
+ """
+ The context of the repository rule containing \
+ helper functions and information about attributes. You get a repository_ctx object \
+ as an argument to the <code>implementation</code> function when you create a \
+ repository rule.
+ """)
 public class StarlarkRepositoryContext extends StarlarkBaseExternalContext {
  private final Rule rule;
  private final PathPackageLocator packageLocator;
@@ -158,8 +160,10 @@ public StarlarkPath getWorkspaceRoot() {
  name = "attr",
  structField = true,
  doc =
- "A struct to access the values of the attributes. The values are provided by "
- + "the user (if not, a default value is used).")
+ """
+ A struct to access the values of the attributes. The values are provided by \
+ the user (if not, a default value is used).
+ """)
  public StructImpl getAttr() {
  return attrObject;
  }
@@ -243,11 +247,13 @@ public void symlink(Object target, Object linkName, StarlarkThread thread)
  @StarlarkMethod(
  name = "template",
  doc =
- "Generates a new file using a <code>template</code>. Every occurrence in "
- + "<code>template</code> of a key of <code>substitutions</code> will be replaced by "
- + "the corresponding value. The result is written in <code>path</code>. An optional"
- + "<code>executable</code> argument (default to true) can be set to turn on or off"
- + "the executable bit.",
+ """
+ Generates a new file using a <code>template</code>. Every occurrence in \
+ <code>template</code> of a key of <code>substitutions</code> will be replaced by \
+ the corresponding value. The result is written in <code>path</code>. An optional \
+ <code>executable</code> argument (default to true) can be set to turn on or off \
+ the executable bit.
+ """,
  useStarlarkThread = true,
  parameters = {
  @Param(
@@ -257,37 +263,39 @@ public void symlink(Object target, Object linkName, StarlarkThread thread)
  @ParamType(type = Label.class),
  @ParamType(type = StarlarkPath.class)
  },
- doc = "path of the file to create, relative to the repository directory."),
+ doc = "Path of the file to create, relative to the repository directory."),
  @Param(
  name = "template",
  allowedTypes = {
  @ParamType(type = String.class),
  @ParamType(type = Label.class),
  @ParamType(type = StarlarkPath.class)
  },
- doc = "path to the template file."),
+ doc = "Path to the template file."),
  @Param(
  name = "substitutions",
  defaultValue = "{}",
  named = true,
- doc = "substitutions to make when expanding the template."),
+ doc = "Substitutions to make when expanding the template."),
  @Param(
  name = "executable",
  defaultValue = "True",
  named = true,
- doc = "set the executable flag on the created file, true by default."),
+ doc = "Set the executable flag on the created file, true by default."),
  @Param(
  name = "watch_template",
  defaultValue = "'auto'",
  positional = false,
  named = true,
  doc =
- "whether to <a href=\"#watch\">watch</a> the template file. Can be the string "
- + "'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking "
- + "the <a href=\"#watch\"><code>watch()</code></a> method; passing 'no' does "
- + "not attempt to watch the file; passing 'auto' will only attempt to watch "
- + "the file when it is legal to do so (see <code>watch()</code> docs for more "
- + "information."),
+ """
+ Whether to <a href="#watch">watch</a> the template file. Can be the string \
+ 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking \
+ the <a href="#watch"><code>watch()</code></a> method; passing 'no' does \
+ not attempt to watch the file; passing 'auto' will only attempt to watch \
+ the file when it is legal to do so (see <code>watch()</code> docs for more \
+ information.
+ """),
  })
  public void createFileFromTemplate(
  Object path,
@@ -356,16 +364,20 @@ protected ImmutableMap<String, String> getRemoteExecProperties() throws EvalExce
  @StarlarkMethod(
  name = "delete",
  doc =
- "Deletes a file or a directory. Returns a bool, indicating whether the file or directory"
- + " was actually deleted by this call.",
+ """
+ Deletes a file or a directory. Returns a bool, indicating whether the file or directory \
+ was actually deleted by this call.
+ """,
  useStarlarkThread = true,
  parameters = {
  @Param(
  name = "path",
  allowedTypes = {@ParamType(type = String.class), @ParamType(type = StarlarkPath.class)},
  doc =
- "Path of the file to delete, relative to the repository directory, or absolute."
- + " Can be a path or a string."),
+ """
+ Path of the file to delete, relative to the repository directory, or absolute. \
+ Can be a path or a string.
+ """),
  })
  public boolean delete(Object pathObject, StarlarkThread thread)
  throws EvalException, RepositoryFunctionException, InterruptedException {
@@ -386,12 +398,14 @@ public boolean delete(Object pathObject, StarlarkThread thread)
  @StarlarkMethod(
  name = "patch",
  doc =
- "Apply a patch file to the root directory of external repository. "
- + "The patch file should be a standard "
- + "<a href=\"https://en.wikipedia.org/wiki/Diff#Unified_format\">"
- + "unified diff format</a> file. "
- + "The Bazel-native patch implementation doesn't support fuzz match and binary patch "
- + "like the patch command line tool.",
+ """
+ Apply a patch file to the root directory of external repository. \
+ The patch file should be a standard \
+ <a href="https://en.wikipedia.org/wiki/Diff#Unified_format"> \
+ unified diff format</a> file. \
+ The Bazel-native patch implementation doesn't support fuzz match and binary patch \
+ like the patch command line tool.
+ """,
  useStarlarkThread = true,
  parameters = {
  @Param(
@@ -402,25 +416,29 @@ public boolean delete(Object pathObject, StarlarkThread thread)
  @ParamType(type = StarlarkPath.class)
  },
  doc =
- "The patch file to apply, it can be label, relative path or absolute path. "
- + "If it's a relative path, it will resolve to the repository directory."),
+ """
+ The patch file to apply, it can be label, relative path or absolute path. \
+ If it's a relative path, it will resolve to the repository directory.
+ """),
  @Param(
  name = "strip",
  named = true,
  defaultValue = "0",
- doc = "strip the specified number of leading components from file names."),
+ doc = "Strip the specified number of leading components from file names."),
  @Param(
  name = "watch_patch",
  defaultValue = "'auto'",
  positional = false,
  named = true,
  doc =
- "whether to <a href=\"#watch\">watch</a> the patch file. Can be the string "
- + "'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking "
- + "the <a href=\"#watch\"><code>watch()</code></a> method; passing 'no' does "
- + "not attempt to watch the file; passing 'auto' will only attempt to watch "
- + "the file when it is legal to do so (see <code>watch()</code> docs for more "
- + "information."),
+ """
+ Whether to <a href="#watch">watch</a> the patch file. Can be the string \
+ 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking \
+ the <a href="#watch"><code>watch()</code></a> method; passing 'no' does \
+ not attempt to watch the file; passing 'auto' will only attempt to watch \
+ the file when it is legal to do so (see <code>watch()</code> docs for more \
+ information.
+ """),
  })
  public void patch(Object patchFile, StarlarkInt stripI, String watchPatch, StarlarkThread thread)
  throws EvalException, RepositoryFunctionException, InterruptedException {
@@ -451,11 +469,13 @@ public void patch(Object patchFile, StarlarkInt stripI, String watchPatch, Starl
  @StarlarkMethod(
  name = "watch_tree",
  doc =
- "Tells Bazel to watch for changes to any files or directories transitively under the "
- + "given path. Any changes to the contents of files, the existence of files or "
- + "directories, file names or directory names, will cause this repo to be "
- + "refetched.<p>Note that attempting to watch paths inside the repo currently being "
- + "fetched will result in an error. ",
+ """
+ Tells Bazel to watch for changes to any files or directories transitively under the \
+ given path. Any changes to the contents of files, the existence of files or \
+ directories, file names or directory names, will cause this repo to be \
+ refetched.<p>Note that attempting to watch paths inside the repo currently being \
+ fetched will result in an error.
+ """,
  parameters = {
  @Param(
  name = "path",
@@ -464,7 +484,7 @@ public void patch(Object patchFile, StarlarkInt stripI, String watchPatch, Starl
  @ParamType(type = Label.class),
  @ParamType(type = StarlarkPath.class)
  },
- doc = "path of the directory tree to watch."),
+ doc = "Path of the directory tree to watch."),
  })
  public void watchTree(Object path)
  throws EvalException, InterruptedException, RepositoryFunctionException {