From 3b70b645ef15bf00f42711ca49ef8defbe2b8e0b Mon Sep 17 00:00:00 2001
From: Googler <arostovtsev@google.com>
Date: Tue, 8 Oct 2024 15:42:03 -0700
Subject: [PATCH] Update existing_rule/s doc (and fix unterminated html tag)

PiperOrigin-RevId: 683789998
Change-Id: I27e2b035be4e797467ab036eb1d4b41ba0947a07
---
 .../StarlarkNativeModuleApi.java              | 19 +++++++++++++------
 1 file changed, 13 insertions(+), 6 deletions(-)

diff --git a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkNativeModuleApi.java b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkNativeModuleApi.java
index 8ed05f17d2755a..db808baf0919bb 100644
--- a/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkNativeModuleApi.java
+++ b/src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkNativeModuleApi.java
@@ -124,10 +124,14 @@ Sequence<?> glob(
               + " whose default value is computed are excluded from the result. (Computed defaults"
               + " cannot be computed until the analysis phase.).</li>" //
               + "</ul>" //
-              + "<p>If possible, avoid using this function. It makes BUILD files brittle and"
-              + " order-dependent. Also, beware that it differs subtly from the two"
-              + " other conversions of rule attribute values from internal form to Starlark: one"
-              + " used by computed defaults, the other used by <code>ctx.attr.foo</code>.",
+              + "<p>If possible, use this function only in <a"
+              + " href=\"https://bazel.build/extending/macros#finalizers\">implementation functions"
+              + " of rule finalizer symbolic macros</a>. Use of this function in other contexts is"
+              + " not recommened, and will be disabled in a future Bazel release; it makes"
+              + " <code>BUILD</code> files brittle and order-dependent. Also, beware that it"
+              + " differs subtly from the two other conversions of rule attribute values from"
+              + " internal form to Starlark: one used by computed defaults, the other used by"
+              + " <code>ctx.attr.foo</code>.",
       parameters = {@Param(name = "name", doc = "The name of the target.")},
       useStarlarkThread = true)
   Object existingRule(String name, StarlarkThread thread) throws EvalException;
@@ -143,8 +147,11 @@ Sequence<?> glob(
               + " <code>x</code> supporting dict-like iteration, <code>len(x)</code>, <code>name in"
               + " x</code>, <code>x[name]</code>, <code>x.get(name)</code>, <code>x.items()</code>,"
               + " <code>x.keys()</code>, and <code>x.values()</code>." //
-              + "<p><em>Note: If possible, avoid using this function. It makes BUILD files brittle"
-              + " and order-dependent.",
+              + "<p>If possible, use this function only in <a"
+              + " href=\"https://bazel.build/extending/macros#finalizers\">implementation functions"
+              + " of rule finalizer symbolic macros</a>. Use of this function in other contexts is"
+              + " not recommened, and will be disabled in a future Bazel release; it makes"
+              + " <code>BUILD</code> files brittle and order-dependent.",
       useStarlarkThread = true)
   Object existingRules(StarlarkThread thread) throws EvalException;