docs for REPO.bazel

Follow-up for #7093 PiperOrigin-RevId: 693795472 Change-Id: Icac2f5658d1579377a38979905214ead9da73dac
bazelbuild · Nov 15, 2024 · 88528dd · 88528dd
1 parent 681c55d
commit 88528dd
Show file tree

Hide file tree

Showing 3 changed files with 28 additions and 4 deletions.
diff --git a/src/main/java/com/google/devtools/build/docgen/annot/GlobalMethods.java b/src/main/java/com/google/devtools/build/docgen/annot/GlobalMethods.java
@@ -40,6 +40,7 @@ enum Environment {
             + " Encyclopedia for extra <a href=\"${link functions}\">functions</a> and build rules,"
             + " which can also be used in BUILD files."),
     MODULE("MODULE.bazel files", "Methods available in MODULE.bazel files."),
+    REPO("REPO.bazel files", "Methods available in REPO.bazel files."),
     VENDOR("VENDOR.bazel files", "Methods available in VENDOR.bazel files."),
     WORKSPACE("WORKSPACE files", "Methods available in WORKSPACE files.");
 

diff --git a/src/main/java/com/google/devtools/build/lib/packages/PackageCallable.java b/src/main/java/com/google/devtools/build/lib/packages/PackageCallable.java
@@ -14,6 +14,8 @@
 
 package com.google.devtools.build.lib.packages;
 
+import com.google.devtools.build.docgen.annot.GlobalMethods;
+import com.google.devtools.build.docgen.annot.GlobalMethods.Environment;
 import java.util.Map;
 import net.starlark.java.annot.Param;
 import net.starlark.java.annot.StarlarkMethod;
@@ -25,6 +27,7 @@
  * Utility class encapsulating the standard definition of the {@code package()} function of BUILD
  * files.
  */
+@GlobalMethods(environment = Environment.BUILD)
 public class PackageCallable {
 
   protected PackageCallable() {}
@@ -33,8 +36,16 @@ protected PackageCallable() {}
 
   @StarlarkMethod(
       name = "package",
-      documented = false, // documented in docgen/templates/be/functions.vm
-      extraKeywords = @Param(name = "kwargs", defaultValue = "{}"),
+      doc =
+          "Declares metadata that applies to every rule in the package. It must be called at "
+              + "most once within a package (BUILD file). If called, it should be the first call "
+              + "in the BUILD file, right after the <code>load()</code> statements.",
+      extraKeywords =
+          @Param(
+              name = "kwargs",
+              doc =
+                  "See the <a href=\"${link functions}#package\"><code>package()</code></a> "
+                      + "function in the Build Encyclopedia for applicable arguments."),
       useStarlarkThread = true)
   public Object packageCallable(Map<String, Object> kwargs, StarlarkThread thread)
       throws EvalException {

diff --git a/src/main/java/com/google/devtools/build/lib/packages/RepoFileGlobals.java b/src/main/java/com/google/devtools/build/lib/packages/RepoFileGlobals.java
@@ -14,6 +14,8 @@
 
 package com.google.devtools.build.lib.packages;
 
+import com.google.devtools.build.docgen.annot.GlobalMethods;
+import com.google.devtools.build.docgen.annot.GlobalMethods.Environment;
 import java.util.Map;
 import net.starlark.java.annot.Param;
 import net.starlark.java.annot.ParamType;
@@ -24,6 +26,7 @@
 import net.starlark.java.eval.StarlarkThread;
 
 /** Definition of the {@code repo()} function used in REPO.bazel files. */
+@GlobalMethods(environment = Environment.REPO)
 public final class RepoFileGlobals {
   private RepoFileGlobals() {}
 
@@ -59,8 +62,17 @@ public void ignoreDirectories(Iterable<?> dirsUnchecked, StarlarkThread thread)
 
   @StarlarkMethod(
       name = "repo",
-      documented = false, // documented separately
-      extraKeywords = @Param(name = "kwargs"),
+      doc =
+          "Declares metadata that applies to every rule in the repository. It must be called at "
+              + "most once per REPO.bazel file. If called, it must be the first call in the "
+              + "REPO.bazel file.",
+      extraKeywords =
+          @Param(
+              name = "kwargs",
+              doc =
+                  "The <code>repo()</code> function accepts exactly the same arguments as the "
+                      + "<a href=\"${link functions}#package\"><code>package()</code></a> function "
+                      + "in BUILD files."),
       useStarlarkThread = true)
   public void repoCallable(Map<String, Object> kwargs, StarlarkThread thread) throws EvalException {
     RepoThreadContext context = RepoThreadContext.fromOrFail(thread, "repo()");