Update documentation about JavaInfo .plugins and .annotation_processing fields.
PiperOrigin-RevId: 413978046
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaAnnotationProcessingApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaAnnotationProcessingApi.java
index aaa2ea7..27557f7 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaAnnotationProcessingApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaAnnotationProcessingApi.java
@@ -36,14 +36,15 @@
@StarlarkMethod(
name = "enabled",
structField = true,
- doc = "Returns true if the Java rule uses annotation processing.")
+ doc = "Deprecated. Returns true if annotation processing was applied on this target.")
boolean usesAnnotationProcessing();
@StarlarkMethod(
name = "class_jar",
structField = true,
allowReturnNones = true,
- doc = "Returns a jar File that is a result of annotation processing for this rule.")
+ doc =
+ "Deprecated: Please use <code>JavaInfo.java_outputs.generated_class_jar</code> instead.")
@Nullable
FileTypeT getGenClassJar();
@@ -51,7 +52,8 @@
name = "source_jar",
structField = true,
allowReturnNones = true,
- doc = "Returns a source archive resulting from annotation processing of this rule.")
+ doc =
+ "Deprecated: Please use <code>JavaInfo.java_outputs.generated_source_jar</code> instead.")
@Nullable
FileTypeT getGenSourceJar();
@@ -59,7 +61,7 @@
name = "transitive_class_jars",
structField = true,
doc =
- "Returns a transitive set of class file jars resulting from annotation "
+ "Deprecated. Returns a transitive set of class file jars resulting from annotation "
+ "processing of this rule and its dependencies.")
Depset /*<FileTypeT>*/ getTransitiveGenClassJarsForStarlark();
@@ -67,19 +69,23 @@
name = "transitive_source_jars",
structField = true,
doc =
- "Returns a transitive set of source archives resulting from annotation processing "
- + "of this rule and its dependencies.")
+ "Deprecated. Returns a transitive set of source archives resulting from annotation "
+ + "processing of this rule and its dependencies.")
Depset /*<FileTypeT>*/ getTransitiveGenSourceJarsForStarlark();
@StarlarkMethod(
name = "processor_classpath",
structField = true,
- doc = "Returns a classpath of annotation processors applied to this rule.")
+ doc =
+ "Deprecated: Please use <code>JavaInfo.plugins</code> instead. Returns a classpath of"
+ + " annotation processors applied to this rule.")
Depset /*<FileTypeT>*/ getProcessorClasspathForStarlark();
@StarlarkMethod(
name = "processor_classnames",
structField = true,
- doc = "Returns class names of annotation processors applied to this rule.")
+ doc =
+ "Deprecated: Please use <code>JavaInfo.plugins</code> instead. Returns class names of"
+ + " annotation processors applied to this rule.")
ImmutableList<String> getProcessorClassNames();
}
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaInfoApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaInfoApi.java
index 7d476be..1a4fced 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaInfoApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaInfoApi.java
@@ -108,7 +108,10 @@
name = "annotation_processing",
structField = true,
allowReturnNones = true,
- doc = "Returns information about annotation processing for this Java/Java-like target.")
+ doc =
+ "Returns information about annotation processors applied on this Java/Java-like target."
+ + "<p>Deprecated: Please use <code>plugins</code> instead (which returns information "
+ + "about annotation processors to be applied by consuming targets).")
@Nullable
JavaAnnotationProcessingApi<?> getGenJarsProvider();
diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaPluginInfoApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaPluginInfoApi.java
index ee9ebe1..13569f4 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaPluginInfoApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/java/JavaPluginInfoApi.java
@@ -42,13 +42,21 @@
JavaPluginDataT extends JavaPluginDataApi,
JavaOutputT extends JavaOutputApi<FileT>>
extends StructApi {
- @StarlarkMethod(name = "plugins", doc = "Returns data about all plugins.", structField = true)
+ @StarlarkMethod(
+ name = "plugins",
+ doc =
+ "Returns data about all plugins that a consuming target should apply."
+ + "<p>This is typically either a <code>java_plugin</code> itself or a "
+ + "<code>java_library</code> exporting one or more plugins. "
+ + "<p>A <code>java_library</code> runs annotation processing with all plugins from "
+ + "this field appearing in <code>deps</code> and <code>plugins</code> attributes.",
+ structField = true)
JavaPluginDataT plugins();
@StarlarkMethod(
name = "api_generating_plugins",
doc =
- "Returns data about API generating plugins. "
+ "Returns data about API generating plugins defined or exported by this target. "
+ "<p>Those annotation processors are applied to a Java target before producing "
+ "its header jars (which contain method signatures). When no API plugins are "
+ "present, header jars are generated from the sources, reducing critical path. "
