Add @StarlarkDeprecated for marking a Starlark symbol as deprecated in docs
This change does not extensively mark all such deprecated symbols in the Starlark API, but introduces the infrastructure to do so in followup changes, and marks a couple of examples as a proof of concept.
RELNOTES: None.
PiperOrigin-RevId: 277164173
diff --git a/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationProcessor.java b/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationProcessor.java
index f0c86cd..c83b254 100644
--- a/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationProcessor.java
+++ b/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationProcessor.java
@@ -105,17 +105,16 @@
}
}
- List<String> globalModules = new ArrayList<>();
+ List<SkylarkModuleDoc> globalModules = new ArrayList<>();
for (SkylarkModuleCategory globalCategory : GLOBAL_CATEGORIES) {
- List<SkylarkModuleDoc> allGlobalModules = modulesByCategory.remove(globalCategory);
- for (SkylarkModuleDoc module : allGlobalModules) {
+ for (SkylarkModuleDoc module : modulesByCategory.remove(globalCategory)) {
if (!module.getName().equals(globalModule.getName())) {
- globalModules.add(module.getName());
+ globalModules.add(module);
}
}
}
- Collections.sort(globalModules, us);
+ Collections.sort(globalModules, (doc1, doc2) -> us.compare(doc1.getName(), doc2.getName()));
writeOverviewPage(
outputDir,
globalModule.getName(),
@@ -172,7 +171,7 @@
String globalModuleName,
List<String> globalFunctions,
List<String> globalConstants,
- List<String> globalModules,
+ List<SkylarkModuleDoc> globalModules,
Map<SkylarkModuleCategory, List<SkylarkModuleDoc>> modulesPerCategory)
throws IOException {
File skylarkDocPath = new File(outputDir + "/skylark-overview.html");
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 79c9d0d..5c0ba8e 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
@@ -18,9 +18,8 @@
import com.google.devtools.build.lib.syntax.EvalUtils;
import java.util.List;
-/**
- * A class representing a Skylark built-in object or method.
- */
+/** A class representing a Skylark built-in object or method. */
+@Deprecated
public final class SkylarkBuiltinMethodDoc extends SkylarkMethodDoc {
private final SkylarkModuleDoc module;
private final SkylarkSignature annotation;
@@ -40,6 +39,11 @@
annotation.extraKeywords());
}
+ @Override
+ public boolean isDeprecated() {
+ return false;
+ }
+
public SkylarkSignature getAnnotation() {
return annotation;
}
diff --git a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkConstructorMethodDoc.java b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkConstructorMethodDoc.java
index 354eccf..8f861ae 100644
--- a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkConstructorMethodDoc.java
+++ b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkConstructorMethodDoc.java
@@ -15,6 +15,7 @@
import com.google.common.collect.ImmutableList;
import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable;
+import com.google.devtools.build.lib.skylarkinterface.StarlarkDeprecated;
import com.google.devtools.build.lib.syntax.EvalUtils;
import java.lang.reflect.Method;
import java.util.List;
@@ -29,6 +30,8 @@
private final Method method;
private final SkylarkCallable callable;
private final ImmutableList<SkylarkParamDoc> params;
+ // TODO(cparsons): Move to superclass when SkylarkBuiltinMethodDoc is removed.
+ private final boolean deprecated;
public SkylarkConstructorMethodDoc(
String fullyQualifiedName, Method method, SkylarkCallable callable) {
@@ -41,6 +44,12 @@
withoutSelfParam(callable, method),
callable.extraPositionals(),
callable.extraKeywords());
+ this.deprecated = method.isAnnotationPresent(StarlarkDeprecated.class);
+ }
+
+ @Override
+ public boolean isDeprecated() {
+ return deprecated;
}
public Method getMethod() {
diff --git a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkDoc.java b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkDoc.java
index 01450e4..9a7edb5 100644
--- a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkDoc.java
+++ b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkDoc.java
@@ -47,6 +47,9 @@
*/
public abstract String getDocumentation();
+ /** Returns true if this entity should be considered "deprecated" for documentation purposes. */
+ public abstract boolean isDeprecated();
+
protected String getTypeAnchor(Class<?> returnType, Class<?> generic1) {
return getTypeAnchor(returnType) + " of " + getTypeAnchor(generic1) + "s";
}
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 6c45539..458a0b3 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
@@ -18,6 +18,7 @@
import com.google.devtools.build.lib.skylarkinterface.Param;
import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable;
import com.google.devtools.build.lib.skylarkinterface.SkylarkInterfaceUtils;
+import com.google.devtools.build.lib.skylarkinterface.StarlarkDeprecated;
import com.google.devtools.build.lib.syntax.EvalUtils;
import com.google.devtools.build.lib.syntax.StarlarkSemantics.FlagIdentifier;
import java.lang.reflect.Method;
@@ -33,6 +34,8 @@
private final Method method;
private final SkylarkCallable callable;
private final ImmutableList<SkylarkParamDoc> params;
+ // TODO(cparsons): Move to superclass when SkylarkBuiltinMethodDoc is removed.
+ private final boolean deprecated;
private boolean isOverloaded;
@@ -47,6 +50,7 @@
withoutSelfParam(callable, method),
callable.extraPositionals(),
callable.extraKeywords());
+ this.deprecated = method.isAnnotationPresent(StarlarkDeprecated.class);
}
public Method getMethod() {
@@ -59,6 +63,11 @@
}
@Override
+ public boolean isDeprecated() {
+ return deprecated;
+ }
+
+ @Override
public String getName() {
// Normally we refer to methods by their name, e.g. "foo" for method foo(arg1, arg2).
// However, if a method is overloaded, the name is no longer unique, which forces us to append
diff --git a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkModuleDoc.java b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkModuleDoc.java
index bdac30a..999f583 100644
--- a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkModuleDoc.java
+++ b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkModuleDoc.java
@@ -21,6 +21,7 @@
import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable;
import com.google.devtools.build.lib.skylarkinterface.SkylarkModule;
import com.google.devtools.build.lib.skylarkinterface.SkylarkSignature;
+import com.google.devtools.build.lib.skylarkinterface.StarlarkDeprecated;
import java.text.Collator;
import java.util.Collection;
import java.util.Locale;
@@ -40,6 +41,7 @@
private final Multimap<String, SkylarkJavaMethodDoc> javaMethods;
private TreeMap<String, SkylarkMethodDoc> methodMap;
private final String title;
+ private final boolean deprecated;
@Nullable private SkylarkConstructorMethodDoc javaConstructor;
public SkylarkModuleDoc(SkylarkModule module, Class<?> classObject) {
@@ -49,6 +51,7 @@
this.builtinMethodMap = new TreeMap<>(Collator.getInstance(Locale.US));
this.methodMap = new TreeMap<>(Collator.getInstance(Locale.US));
this.javaMethods = HashMultimap.<String, SkylarkJavaMethodDoc>create();
+ this.deprecated = classObject.isAnnotationPresent(StarlarkDeprecated.class);
if (module.title().isEmpty()) {
this.title = module.name();
} else {
@@ -70,6 +73,11 @@
return title;
}
+ @Override
+ public boolean isDeprecated() {
+ return deprecated;
+ }
+
public SkylarkModule getAnnotation() {
return module;
}
diff --git a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkParamDoc.java b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkParamDoc.java
index 87a4910..9bf96c4 100644
--- a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkParamDoc.java
+++ b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkParamDoc.java
@@ -91,4 +91,10 @@
}
return prefixWarning + SkylarkDocUtils.substituteVariables(param.doc());
}
+
+ @Override
+ public boolean isDeprecated() {
+ // TODO(cparsons): Implement for deprecated parameters.
+ return false;
+ }
}
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/skylark-library.vm b/src/main/java/com/google/devtools/build/docgen/templates/skylark-library.vm
index d8b852b..58bc1ca 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/skylark-library.vm
+++ b/src/main/java/com/google/devtools/build/docgen/templates/skylark-library.vm
@@ -17,7 +17,12 @@
<ul>
#foreach ($method in $module.methods)
#if ($method.documented())
- <li><a href="#${method.name}">${method.name}</a></li>
+ <li>
+ <a href="#${method.name}">${method.name}</a>
+ #if (${method.deprecated})
+ (Deprecated)
+ #end
+ </li>
#end
#end
</ul>
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/skylark-overview.vm b/src/main/java/com/google/devtools/build/docgen/templates/skylark-overview.vm
index 0bd7a73..2bb357e 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/skylark-overview.vm
+++ b/src/main/java/com/google/devtools/build/docgen/templates/skylark-overview.vm
@@ -60,14 +60,18 @@
<div class="toc">
<ul>
-#foreach ($name in $global_modules)
+#foreach ($module in $global_modules)
<li>
- <a href="/versions/{{ site.version }}/skylark/lib/${name}.html">${name}</a>
+ <a href="/versions/{{ site.version }}/skylark/lib/${module.name}.html">${module.name}</a>
+ #if (${module.deprecated})
+ (Deprecated)
+ #end
+
</li>
#end
@@ -91,7 +95,9 @@
<a href="/versions/{{ site.version }}/skylark/lib/${module.name}.html">${module.title}</a>
-
+ #if (${module.deprecated})
+ (Deprecated)
+ #end
</li>
#end
diff --git a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkCommandLineApi.java b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkCommandLineApi.java
index f8c8835..2aaeb7a 100644
--- a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkCommandLineApi.java
+++ b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkCommandLineApi.java
@@ -18,6 +18,7 @@
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.skylarkinterface.StarlarkDeprecated;
import com.google.devtools.build.lib.syntax.EvalException;
import com.google.devtools.build.lib.syntax.SkylarkNestedSet;
@@ -27,6 +28,7 @@
namespace = true,
category = SkylarkModuleCategory.TOP_LEVEL_TYPE,
doc = "Deprecated. Module for creating memory efficient command lines.")
+@StarlarkDeprecated
public interface SkylarkCommandLineApi {
@SkylarkCallable(
diff --git a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/apple/AppleConfigurationApi.java b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/apple/AppleConfigurationApi.java
index 2a88d94..8d5e042 100644
--- a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/apple/AppleConfigurationApi.java
+++ b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/apple/AppleConfigurationApi.java
@@ -18,6 +18,7 @@
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.skylarkinterface.StarlarkDeprecated;
/** An interface for a configuration type containing info for Apple platforms and tools. */
@SkylarkModule(
@@ -29,8 +30,10 @@
@SkylarkCallable(
name = "ios_cpu",
- doc = "<b>Deprecated. Use <a href='#single_arch_cpu'>single_arch_cpu</a> instead.</b> "
- + "The value of ios_cpu for this configuration.")
+ doc =
+ "<b>Deprecated. Use <a href='#single_arch_cpu'>single_arch_cpu</a> instead.</b> "
+ + "The value of ios_cpu for this configuration.")
+ @StarlarkDeprecated
public String getIosCpu();
@SkylarkCallable(
diff --git a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/java/JavaSkylarkApiProviderApi.java b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/java/JavaSkylarkApiProviderApi.java
index 041ba12..f100116 100644
--- a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/java/JavaSkylarkApiProviderApi.java
+++ b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/java/JavaSkylarkApiProviderApi.java
@@ -17,6 +17,7 @@
import com.google.devtools.build.lib.skylarkbuildapi.FileApi;
import com.google.devtools.build.lib.skylarkinterface.SkylarkModule;
import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory;
+import com.google.devtools.build.lib.skylarkinterface.StarlarkDeprecated;
/**
* Provides access to information about Java rules. Every Java-related target provides this struct,
@@ -30,4 +31,5 @@
"Deprecated. Use <a"
+ " href=\"https://docs.bazel.build/versions/master/skylark/lib/JavaInfo.html\">JavaInfo</a>"
+ " instead.")
+@StarlarkDeprecated
public interface JavaSkylarkApiProviderApi<FileT extends FileApi> {}
diff --git a/src/main/java/com/google/devtools/build/lib/skylarkinterface/StarlarkDeprecated.java b/src/main/java/com/google/devtools/build/lib/skylarkinterface/StarlarkDeprecated.java
new file mode 100644
index 0000000..3477f0b
--- /dev/null
+++ b/src/main/java/com/google/devtools/build/lib/skylarkinterface/StarlarkDeprecated.java
@@ -0,0 +1,30 @@
+// Copyright 2019 The Bazel Authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+package com.google.devtools.build.lib.skylarkinterface;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * An annotation to mark a Starlark symbol as "deprecated" for documentation purposes.
+ *
+ * <p>This annotation should be used only for documentation purposes. This does not necessarily
+ * indicate that the annotated java element should be considered deprecated. For example, a method
+ * may be deprecated as a Starlark-exposed method, but encouraged from java callsites.
+ */
+@Target({ElementType.TYPE, ElementType.METHOD})
+@Retention(RetentionPolicy.RUNTIME)
+public @interface StarlarkDeprecated {}
