Explicitly specify @SkylarkCallable parameters for cpp skylark modules.

RELNOTES: None. PiperOrigin-RevId: 202015490
bazelbuild · Jun 25, 2018 · 1f684e1 · 1f684e1
1 parent 73a7c90
commit 1f684e1
Show file tree

Hide file tree

Showing 2 changed files with 131 additions and 13 deletions.
diff --git a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/cpp/CcToolchainProviderApi.java b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/cpp/CcToolchainProviderApi.java
@@ -16,9 +16,11 @@
 
 import com.google.common.collect.ImmutableList;
 import com.google.devtools.build.lib.skylarkbuildapi.platform.ToolchainInfoApi;
+import com.google.devtools.build.lib.skylarkinterface.Param;
 import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable;
 import com.google.devtools.build.lib.skylarkinterface.SkylarkModule;
 import com.google.devtools.build.lib.syntax.EvalException;
+import com.google.devtools.build.lib.syntax.SkylarkList;
 
 /** Information about the C++ toolchain. */
 @SkylarkModule(name = "CcToolchainInfo", doc = "Information about the C++ compiler being used.")
@@ -54,8 +56,18 @@ public interface CcToolchainProviderApi extends ToolchainInfoApi {
   @SkylarkCallable(
       name = "unfiltered_compiler_options",
       doc =
-          "Returns the default list of options which cannot be filtered by BUILD "
-              + "rules. These should be appended to the command line after filtering.")
+          "<b>Deprecated</b>. Returns the default list of options which cannot be filtered by "
+          + "BUILD rules. These should be appended to the command line after filtering.",
+      parameters = {
+        @Param(
+            name = "features",
+            doc = "Unused.",
+            positional = true,
+            named = false,
+            type = SkylarkList.class
+        )
+      }
+  )
   // TODO(b/24373706): Remove this method once new C++ toolchain API is available
   public ImmutableList<String> getUnfilteredCompilerOptionsWithSysroot(
       Iterable<String> featuresNotUsedAnymore);
@@ -109,7 +121,17 @@ public ImmutableList<String> getUnfilteredCompilerOptionsWithSysroot(
       doc =
           "Returns the immutable list of linker options for fully statically linked "
               + "outputs. Does not include command-line options passed via --linkopt or "
-              + "--linkopts.")
+              + "--linkopts.",
+      parameters = {
+        @Param(
+            name = "shared_lib",
+            doc = "If true, returns the link options for a shared library.",
+            positional = true,
+            named = false,
+            type = Boolean.class
+        )
+      }
+  )
   @Deprecated
   public ImmutableList<String> getFullyStaticLinkOptions(Boolean sharedLib) throws EvalException;
 
@@ -118,7 +140,17 @@ public ImmutableList<String> getUnfilteredCompilerOptionsWithSysroot(
       doc =
           "Returns the immutable list of linker options for mostly statically linked "
               + "outputs. Does not include command-line options passed via --linkopt or "
-              + "--linkopts.")
+              + "--linkopts.",
+      parameters = {
+        @Param(
+            name = "shared_lib",
+            doc = "If true, returns the link options for a shared library.",
+            positional = true,
+            named = false,
+            type = Boolean.class
+        )
+      }
+  )
   @Deprecated
   public ImmutableList<String> getMostlyStaticLinkOptions(Boolean sharedLib);
 
@@ -127,7 +159,16 @@ public ImmutableList<String> getUnfilteredCompilerOptionsWithSysroot(
       doc =
           "Returns the immutable list of linker options for artifacts that are not "
               + "fully or mostly statically linked. Does not include command-line options "
-              + "passed via --linkopt or --linkopts."
+              + "passed via --linkopt or --linkopts.",
+      parameters = {
+        @Param(
+            name = "shared_lib",
+            doc = "If true, returns the link options for a shared library.",
+            positional = true,
+            named = false,
+            type = Boolean.class
+        )
+      }
   )
   @Deprecated
   public ImmutableList<String> getDynamicLinkOptions(Boolean sharedLib);

diff --git a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/cpp/CppConfigurationApi.java b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/cpp/CppConfigurationApi.java
@@ -15,10 +15,12 @@
 package com.google.devtools.build.lib.skylarkbuildapi.cpp;
 
 import com.google.common.collect.ImmutableList;
+import com.google.devtools.build.lib.skylarkinterface.Param;
 import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable;
 import com.google.devtools.build.lib.skylarkinterface.SkylarkModule;
 import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory;
 import com.google.devtools.build.lib.syntax.EvalException;
+import com.google.devtools.build.lib.syntax.SkylarkList;
 
 /**
  * The C++ configuration fragment.
@@ -62,10 +64,19 @@ public ImmutableList<String> getBuiltInIncludeDirectoriesForSkylark()
   @SkylarkCallable(
     name = "compiler_options",
     doc =
-        "Returns the default options to use for compiling C, C++, and assembler. "
-            + "This is just the options that should be used for all three languages. "
+        "<b>Deprecated.</b> Returns the default options to use for compiling C, C++, and "
+            + "assembler. This is just the options that should be used for all three languages. "
             + "There may be additional C-specific or C++-specific options that should be used, "
-            + "in addition to the ones returned by this method"
+            + "in addition to the ones returned by this method",
+    parameters = {
+      @Param(
+          name = "features",
+          doc = "Unused.",
+          positional = true,
+          named = false,
+          type = SkylarkList.class
+      )
+    }
   )
   @Deprecated
   public ImmutableList<String> getCompilerOptions(Iterable<String> featuresNotUsedAnymore);
@@ -84,7 +95,16 @@ public ImmutableList<String> getBuiltInIncludeDirectoriesForSkylark()
     doc =
         "Returns the list of additional C++-specific options to use for compiling C++. "
             + "These should be go on the command line after the common options returned by "
-            + "<code>compiler_options</code>"
+            + "<code>compiler_options</code>",
+    parameters = {
+      @Param(
+          name = "features",
+          doc = "Unused.",
+          positional = true,
+          named = false,
+          type = SkylarkList.class
+      )
+    }
   )
   @Deprecated
   public ImmutableList<String> getCxxOptions(Iterable<String> featuresNotUsedAnymore);
@@ -93,7 +113,16 @@ public ImmutableList<String> getBuiltInIncludeDirectoriesForSkylark()
     name = "unfiltered_compiler_options",
     doc =
         "Returns the default list of options which cannot be filtered by BUILD "
-            + "rules. These should be appended to the command line after filtering."
+            + "rules. These should be appended to the command line after filtering.",
+    parameters = {
+      @Param(
+          name = "features",
+          doc = "Unused.",
+          positional = true,
+          named = false,
+          type = SkylarkList.class
+      )
+    }
   )
   public ImmutableList<String> getUnfilteredCompilerOptionsWithLegacySysroot(
       Iterable<String> featuresNotUsedAnymore);
@@ -112,7 +141,23 @@ public ImmutableList<String> getUnfilteredCompilerOptionsWithLegacySysroot(
     doc =
         "Returns the immutable list of linker options for fully statically linked "
             + "outputs. Does not include command-line options passed via --linkopt or "
-            + "--linkopts."
+            + "--linkopts.",
+    parameters = {
+      @Param(
+          name = "features",
+          doc = "Unused.",
+          positional = true,
+          named = false,
+          type = SkylarkList.class
+      ),
+      @Param(
+          name = "shared_lib",
+          doc = "If true, returns the link options for a shared library.",
+          positional = true,
+          named = false,
+          type = Boolean.class
+      )
+    }
   )
   @Deprecated
   public ImmutableList<String> getFullyStaticLinkOptions(
@@ -123,7 +168,23 @@ public ImmutableList<String> getFullyStaticLinkOptions(
     doc =
         "Returns the immutable list of linker options for mostly statically linked "
             + "outputs. Does not include command-line options passed via --linkopt or "
-            + "--linkopts."
+            + "--linkopts.",
+    parameters = {
+      @Param(
+          name = "features",
+          doc = "Unused.",
+          positional = true,
+          named = false,
+          type = SkylarkList.class
+      ),
+      @Param(
+          name = "shared_lib",
+          doc = "If true, returns the link options for a shared library.",
+          positional = true,
+          named = false,
+          type = Boolean.class
+      )
+    }
   )
   @Deprecated
   public ImmutableList<String> getMostlyStaticLinkOptions(
@@ -134,7 +195,23 @@ public ImmutableList<String> getMostlyStaticLinkOptions(
     doc =
         "Returns the immutable list of linker options for artifacts that are not "
             + "fully or mostly statically linked. Does not include command-line options "
-            + "passed via --linkopt or --linkopts."
+            + "passed via --linkopt or --linkopts.",
+    parameters = {
+      @Param(
+          name = "features",
+          doc = "Unused.",
+          positional = true,
+          named = false,
+          type = SkylarkList.class
+      ),
+      @Param(
+          name = "shared_lib",
+          doc = "If true, returns the link options for a shared library.",
+          positional = true,
+          named = false,
+          type = Boolean.class
+      )
+    }
   )
   @Deprecated
   public ImmutableList<String> getDynamicLinkOptions(