Clarify documentation; use short_path, not path, in runfiles

I just went on a wild goose chase trying to figure out why `path` was returning the wrong thing when using the file in `runfiles`. It was all there in the documentation for `short_path`, but I was looking at the documentation for `path`.

I think adding this runfiles hint might have helped me, and I think clarifying the first sentence would have led me down the right track.

--
Reviewed-on: https://github.com/bazelbuild/bazel/pull/919
MOS_MIGRATED_REVID=114850771

1 files changed, 22 insertions, 11 deletions

diff --git a/src/main/java/com/google/devtools/build/lib/actions/Artifact.java b/src/main/java/com/google/devtools/build/lib/actions/Artifact.java
index 2a700023ce..0c37860847 100644
--- a/src/main/java/com/google/devtools/build/lib/actions/Artifact.java
+++ b/src/main/java/com/google/devtools/build/lib/actions/Artifact.java
@@ -438,13 +438,20 @@ public class Artifact implements FileType.HasFilename, ArtifactFile, SkylarkValu
    * Returns this.getExecPath().getPathString().
    */
   @Override
-  @SkylarkCallable(name = "path", structField = true,
-      doc = "The execution path of this file, relative to the execution directory. It consists of "
-      + "two parts, an optional first part called the <i>root</i> (see also the <a "
-      + "href=\"root.html\">root</a> module), and the second part which is the "
-      + "<code>short_path</code>. The root may be empty, which it usually is for non-generated "
-      + "files. For generated files it usually contains a configuration-specific path fragment that"
-      + " encodes things like the target CPU architecture that was used while building said file.")
+  @SkylarkCallable(
+    name = "path",
+    structField = true,
+    doc =
+        "The execution path of this file, relative to the workspace's execution directory. It "
+            + "consists of two parts, an optional first part called the <i>root</i> (see also the "
+            + "<a href=\"root.html\">root</a> module), and the second part which is the "
+            + "<code>short_path</code>. The root may be empty, which it usually is for "
+            + "non-generated files. For generated files it usually contains a "
+            + "configuration-specific path fragment that encodes things like the target CPU "
+            + "architecture that was used while building said file. Use the "
+            + "<code>short_path</code> for the path under which the file is mapped if it's in the "
+            + "runfiles of a binary."
+  )
   public final String getExecPathString() {
     return getExecPath().getPathString();
   }
@@ -456,10 +463,14 @@ public class Artifact implements FileType.HasFilename, ArtifactFile, SkylarkValu
     return ShellUtils.shellEscape(getExecPathString());
   }
 
-  @SkylarkCallable(name = "short_path", structField = true,
-      doc = "The path of this file relative to its root. This excludes the aforementioned "
-      + "<i>root</i>, i.e. configuration-specific fragments of the path. This is also the path "
-      + "under which the file is mapped if its in the runfiles of a binary.")
+  @SkylarkCallable(
+    name = "short_path",
+    structField = true,
+    doc =
+        "The path of this file relative to its root. This excludes the aforementioned "
+            + "<i>root</i>, i.e. configuration-specific fragments of the path. This is also the "
+            + "path under which the file is mapped if it's in the runfiles of a binary."
+  )
   public final String getRootRelativePathString() {
     return getRootRelativePath().getPathString();
   }