From 46d5936003e6a9fc20fb04f49eb20bc72b646b93 Mon Sep 17 00:00:00 2001
From: ilist <ilist@google.com>
Date: Tue, 23 Nov 2021 23:32:02 -0800
Subject: [PATCH] Fix documentation in JavaInfo to avoid circular reference.

Mark transitive_runtime_deps deprecated in favour of transitive_runtime_jars.
Mark transitive_deps deprecated in favour of transitive_compile_time_jars.

There might be personal opinions about that (_jars prefix is more common in java_common), but just saying that both getters are legacy and not saying which one to use creates an unnecessary cognitive load.

PiperOrigin-RevId: 411974807
---
 .../starlarkbuildapi/java/JavaInfoApi.java    | 24 ++++++-------------
 1 file changed, 7 insertions(+), 17 deletions(-)

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 eb2a50f1df6b0a..e923523c200098 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
@@ -48,21 +48,13 @@ public interface JavaInfoApi<
 
   @StarlarkMethod(
       name = "transitive_runtime_jars",
-      doc =
-          "Returns a transitive set of Jars required on the target's runtime classpath. Returns"
-              + " the same as <code><a class=\"anchor\""
-              + " href=\"JavaInfo.html#transitive_runtime_deps\">JavaInfo.transitive_runtime_deps"
-              + "</a></code> for legacy reasons.",
+      doc = "Returns a transitive set of Jars required on the target's runtime classpath.",
       structField = true)
   Depset getTransitiveRuntimeJars();
 
   @StarlarkMethod(
       name = "transitive_compile_time_jars",
-      doc =
-          "Returns the transitive set of Jars required to build the target. Returns the same as"
-              + " <code><a class=\"anchor\""
-              + " href=\"JavaInfo.html#transitive_deps\">JavaInfo.transitive_deps</a></code> for"
-              + " legacy reasons.",
+      doc = "Returns the transitive set of Jars required to build the target.",
       structField = true)
   Depset getTransitiveCompileTimeJars();
 
@@ -139,20 +131,18 @@ public interface JavaInfoApi<
   @StarlarkMethod(
       name = "transitive_deps",
       doc =
-          "Returns the transitive set of Jars required to build the target. Returns the same as"
-              + " <code><a class=\"anchor\""
-              + " href=\"JavaInfo.html#transitive_compile_time_jars\">JavaInfo.transitive_compile_time_jars</a></code>"
-              + " for legacy reasons.",
+          "Deprecated: Please use <code><a class=\"anchor\" "
+              + "href=\"JavaInfo.html#transitive_compile_time_jars\">JavaInfo.transitive_compile_time_jars</a></code>"
+              + " instead. It returns the same value.",
       structField = true)
   Depset /*<FileT>*/ getTransitiveDeps();
 
   @StarlarkMethod(
       name = "transitive_runtime_deps",
       doc =
-          "Returns the transitive set of Jars required on the target's runtime classpath. Returns"
-              + " the same as <code><a class=\"anchor\""
+          "Deprecated: please use <code><a class=\"anchor\""
               + " href=\"JavaInfo.html#transitive_runtime_jars\">JavaInfo.transitive_runtime_jars"
-              + "</a></code> for legacy reasons.",
+              + "</a></code> instead. It returns the same value",
       structField = true)
   Depset /*<FileT>*/ getTransitiveRuntimeDeps();