Introduce extraPositonals and extraArguments to SkylarkCallable, to have parity with @SkylarkSignature.

This is necessary for several builtin functions that still use @SkylarkSignature, such as string format. These will be migrated in a future CL.

RELNOTES: None.
PiperOrigin-RevId: 192200282

4 files changed, 39 insertions, 25 deletions

diff --git a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkBuiltinMethodDoc.java b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkBuiltinMethodDoc.java
index bcb52923f9..4a2c5f8bad 100644
--- a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkBuiltinMethodDoc.java
+++ b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkBuiltinMethodDoc.java
@@ -13,10 +13,8 @@
 // limitations under the License.
 package com.google.devtools.build.docgen.skylark;
 
-import com.google.devtools.build.lib.skylarkinterface.Param;
 import com.google.devtools.build.lib.skylarkinterface.SkylarkSignature;
 import com.google.devtools.build.lib.syntax.BaseFunction;
-import java.util.ArrayList;
 import java.util.List;
 
 /**
@@ -33,8 +31,12 @@ public final class SkylarkBuiltinMethodDoc extends SkylarkMethodDoc {
     this.module = module;
     this.annotation = annotation;
     this.fieldClass = fieldClass;
-    this.params = new ArrayList<>();
-    processParams();
+    this.params =
+        SkylarkDocUtils.determineParams(
+            this,
+            annotation.parameters(),
+            annotation.extraPositionals(),
+            annotation.extraKeywords());
   }
 
   public SkylarkSignature getAnnotation() {
@@ -78,20 +80,4 @@ public final class SkylarkBuiltinMethodDoc extends SkylarkMethodDoc {
   public List<SkylarkParamDoc> getParams() {
     return params;
   }
-
-  private void processParams() {
-    processParams(adjustedParameters(annotation));
-    if (!annotation.extraPositionals().name().isEmpty()) {
-      this.params.add(new SkylarkParamDoc(this, annotation.extraPositionals()));
-    }
-    if (!annotation.extraKeywords().name().isEmpty()) {
-      this.params.add(new SkylarkParamDoc(this, annotation.extraKeywords()));
-    }
-  }
-
-  private void processParams(Param[] params) {
-    for (Param param : params) {
-      this.params.add(new SkylarkParamDoc(this, param));
-    }
-  }
 }
diff --git a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkDocUtils.java b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkDocUtils.java
index ac73f65596..18300683af 100644
--- a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkDocUtils.java
+++ b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkDocUtils.java
@@ -14,7 +14,9 @@
 
 package com.google.devtools.build.docgen.skylark;
 
+import com.google.common.collect.ImmutableList;
 import com.google.devtools.build.docgen.DocgenConsts;
+import com.google.devtools.build.lib.skylarkinterface.Param;
 
 /** A utility class for the documentation generator. */
 public final class SkylarkDocUtils {
@@ -30,4 +32,26 @@ public final class SkylarkDocUtils {
         .replace("$BE_ROOT", DocgenConsts.BeDocsRoot)
         .replace("$DOC_EXT", DocgenConsts.documentationExtension);
   }
+
+  /**
+   * Returns a list of parameter documentation elements for a given method doc and the method's
+   * parameters.
+   */
+  static ImmutableList<SkylarkParamDoc> determineParams(
+      SkylarkMethodDoc methodDoc,
+      Param[] userSuppliedParams,
+      Param extraPositionals,
+      Param extraKeywords) {
+    ImmutableList.Builder<SkylarkParamDoc> paramsBuilder = ImmutableList.builder();
+    for (Param param : userSuppliedParams) {
+      paramsBuilder.add(new SkylarkParamDoc(methodDoc, param));
+    }
+    if (!extraPositionals.name().isEmpty()) {
+      paramsBuilder.add(new SkylarkParamDoc(methodDoc, extraPositionals));
+    }
+    if (!extraKeywords.name().isEmpty()) {
+      paramsBuilder.add(new SkylarkParamDoc(methodDoc, extraKeywords));
+    }
+    return paramsBuilder.build();
+  }
 }
diff --git a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkJavaMethodDoc.java b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkJavaMethodDoc.java
index fe92bdfe90..60ca32e093 100644
--- a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkJavaMethodDoc.java
+++ b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkJavaMethodDoc.java
@@ -42,11 +42,9 @@ public final class SkylarkJavaMethodDoc extends SkylarkMethodDoc {
         : callable.name();
     this.method = method;
     this.callable = callable;
-    ImmutableList.Builder<SkylarkParamDoc> paramsBuilder = ImmutableList.builder();
-    for (Param param : callable.parameters()) {
-      paramsBuilder.add(new SkylarkParamDoc(this, param));
-    }
-    this.params = paramsBuilder.build();
+    this.params =
+        SkylarkDocUtils.determineParams(
+            this, callable.parameters(), callable.extraPositionals(), callable.extraKeywords());
   }
 
   public Method getMethod() {
diff --git a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkMethodDoc.java b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkMethodDoc.java
index 116fd4a528..b617803612 100644
--- a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkMethodDoc.java
+++ b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkMethodDoc.java
@@ -72,6 +72,12 @@ public abstract class SkylarkMethodDoc extends SkylarkDoc {
       }
       argList.add(formatParameter(param));
     }
+    if (!annotation.extraPositionals().name().isEmpty()) {
+      argList.add("*" + annotation.extraPositionals().name());
+    }
+    if (!annotation.extraKeywords().name().isEmpty()) {
+      argList.add("**" + annotation.extraKeywords().name());
+    }
     return Joiner.on(", ").join(argList);
   }