From 710fc96793247e1d042ac1f4f785541654ab0db9 Mon Sep 17 00:00:00 2001
From: Xdng Yng <wyverald@gmail.com>
Date: Wed, 6 Nov 2024 11:12:20 -0800
Subject: [PATCH] docs for REPO.bazel

Follow-up for https://github.com/bazelbuild/bazel/issues/7093

PiperOrigin-RevId: 693795472
Change-Id: Icac2f5658d1579377a38979905214ead9da73dac
---
 .../build/docgen/annot/GlobalMethods.java        |  1 +
 .../build/lib/packages/PackageCallable.java      | 15 +++++++++++++--
 .../build/lib/packages/RepoFileGlobals.java      | 16 ++++++++++++++--
 3 files changed, 28 insertions(+), 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
index 0fdeb668031d15..a61d20261cc084 100644
--- 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
index 0a9efa721c0b07..50411f03e987f7 100644
--- 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
index 07631e1763e459..8fb5eb5f85bacf 100644
--- 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()");