From 22a49945705dc86d3baa3f3420700b3f88ecbc25 Mon Sep 17 00:00:00 2001
From: laurentlb <laurentlb@google.com>
Date: Wed, 29 Aug 2018 09:52:12 -0700
Subject: [PATCH] Update documentation of expand_location

Make explicit in which case the function is useful. Most rules
won't need it.

https://github.com/bazelbuild/bazel/issues/6001

RELNOTES: None.
PiperOrigin-RevId: 210738068
---
 .../build/lib/skylarkbuildapi/SkylarkRuleContextApi.java    | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkRuleContextApi.java b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkRuleContextApi.java
index 0860dc3944b236..a8d039a093c070 100644
--- a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkRuleContextApi.java
+++ b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkRuleContextApi.java
@@ -726,7 +726,11 @@ public Runtime.NoneType action(
             + "<code>$(location ...)</code> will cause an error if the referenced target has "
             + "multiple outputs. In this case, please use <code>$(locations ...)</code> since it "
             + "produces a space-separated list of output paths. It can be safely used for a "
-            + "single output file, too.",
+            + "single output file, too."
+            + "<br/><br/>"
+            + "This function is useful to let the user specify a command in a BUILD file (like "
+            + "for <code>genrule</code>). In other cases, it is often better to manipulate labels "
+            + "directly.",
     parameters = {
       @Param(name = "input", type = String.class, doc = "String to be expanded."),
       @Param(