Skylark: Added more documentation for ctx.expand_location.

--
MOS_MIGRATED_REVID=125558637

src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleImplementationFunctions.java

diff --git a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleImplementationFunctions.java b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleImplementationFunctions.java
index 3245c53..de3dfd6 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleImplementationFunctions.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleImplementationFunctions.java
@@ -349,9 +349,13 @@
 
   @SkylarkSignature(name = "expand_location",
       doc =
-      "Expands the given string so that all labels are replaced with the location "
-      + "of their target file(s). Currently, the algorithm uses output, srcs, deps, "
-      + "tools and data attributes for looking up mappings from label to locations.",
+      "Expands all <code>$(location ...)</code> templates in the given string by replacing "
+      + "<code>$(location //x)</code> with the path of the output file of target //x. "
+      + "Expansion only works for labels that point to direct dependencies of this rule or that "
+      + "are explicitly listed in the optional argument <code>targets</code>.<br/>"
+      + "<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.",
       objectType = SkylarkRuleContext.class, returnType = String.class,
       parameters = {
           @Param(name = "self", type = SkylarkRuleContext.class, doc = "this context"),
@@ -649,7 +653,8 @@
         defaultValue = "False",
         named = true,
         positional = false,
-        doc = "shall we expand $(location) variables?"
+        doc = "shall we expand $(location) variables? " 
+            + "See <a href=\"#expand_location\">ctx.expand_location()</a> for more details."
       ),
       @Param(
         name = "make_variables",