From a2ee2e051cfb9ef69eb62e967ac7bcab8c89b820 Mon Sep 17 00:00:00 2001
From: Fabian Meumertzheim <fabian@meumertzhe.im>
Date: Fri, 15 Sep 2023 13:26:11 -0700
Subject: [PATCH] Explain the use of `str(Label(...))` in the docs

Closes #19509.

PiperOrigin-RevId: 565763282
Change-Id: I0a8ede20b6bda5140a83c03a44577c034a54dd5f
---
 .../com/google/devtools/build/lib/cmdline/Label.java     | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/src/main/java/com/google/devtools/build/lib/cmdline/Label.java b/src/main/java/com/google/devtools/build/lib/cmdline/Label.java
index 7ff3ef9d36e0eb..e2b136c9676c23 100644
--- a/src/main/java/com/google/devtools/build/lib/cmdline/Label.java
+++ b/src/main/java/com/google/devtools/build/lib/cmdline/Label.java
@@ -53,7 +53,14 @@
  *
  * <p>Parsing is robust against bad input, for example, from the command line.
  */
-@StarlarkBuiltin(name = "Label", category = DocCategory.BUILTIN, doc = "A BUILD target identifier.")
+@StarlarkBuiltin(
+    name = "Label",
+    category = DocCategory.BUILTIN,
+    doc =
+        "A BUILD target identifier."
+            + "<p>For every <code>Label<code> instance <code>l</code>, the string representation"
+            + " <code>str(l)</code> has the property that <code>Label(str(l)) == l</code>,"
+            + " regardless of where the <code>Label()</code> call occurs.")
 @AutoCodec
 @Immutable
 @ThreadSafe