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
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 2a70002..0c37860 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 @@
* 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 @@
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();
}
