runfiles libraries: fix tests and comments

- Update all runfiles libraries to have the same
  header comment format, including the build rule
  to depend on the namespace / header / module to
  import

- Fix runfiles_test.cc to include the right files
  (recent refactoring commit has split
  src/main/cpp/util/path.cc from
  file_[platform].cc)

- Change exported variable
  _rlocation_isabs_pattern in runfiles.bash to be
  upper-case, so it is visibly a variable and not
  a function.

See https://github.com/bazelbuild/bazel/issues/4460

Change-Id: I17e18308506ab9f5c9f410ef6bc6b9df912d42a9

Closes #5481.

Change-Id: I17e18308506ab9f5c9f410ef6bc6b9df912d42a9
PiperOrigin-RevId: 202291629

1 files changed, 34 insertions, 20 deletions

diff --git a/tools/python/runfiles/runfiles.py b/tools/python/runfiles/runfiles.py
index e80a7d19a9..cdf62b62b9 100644
--- a/tools/python/runfiles/runfiles.py
+++ b/tools/python/runfiles/runfiles.py
@@ -13,35 +13,49 @@
 # limitations under the License.
 """Runfiles lookup library for Bazel-built Python binaries and tests.
 
-Usage:
+USAGE:
 
-from bazel_tools.tools.python.runfiles import runfiles
+1.  Depend on this runfiles library from your build rule:
 
-r = runfiles.Create()
-with open(r.Rlocation("io_bazel/foo/bar.txt"), "r") as f:
-  contents = f.readlines()
+      py_binary(
+          name = "my_binary",
+          ...
+          deps = ["@bazel_tools//tools/python/runfiles"],
+      )
 
-The code above creates a manifest- or directory-based implementations based on
-the environment variables in os.environ. See `Create()` for more info.
+2.  Import the runfiles library.
 
-If you want to explicitly create a manifest- or directory-based
-implementations, you can do so as follows:
+      from bazel_tools.tools.python.runfiles import runfiles
 
-  r1 = runfiles.CreateManifestBased("path/to/foo.runfiles_manifest")
+3.  Create a Runfiles object and use rlocation to look up runfile paths:
 
-  r2 = runfiles.CreateDirectoryBased("path/to/foo.runfiles/")
+      r = runfiles.Create()
+      ...
+      with open(r.Rlocation("my_workspace/path/to/my/data.txt"), "r") as f:
+        contents = f.readlines()
+        ...
 
-If you want to start subprocesses that also need runfiles, you need to set the
-right environment variables for them:
+    The code above creates a manifest- or directory-based implementations based
+    on the environment variables in os.environ. See `Create()` for more info.
 
-  import subprocess
-  from bazel_tools.tools.python.runfiles import runfiles
+    If you want to explicitly create a manifest- or directory-based
+    implementations, you can do so as follows:
 
-  r = runfiles.Create()
-  env = {}
-  ...
-  env.update(r.EnvVars())
-  p = subprocess.Popen([r.Rlocation("path/to/binary")], env, ...)
+      r1 = runfiles.CreateManifestBased("path/to/foo.runfiles_manifest")
+
+      r2 = runfiles.CreateDirectoryBased("path/to/foo.runfiles/")
+
+    If you want to start subprocesses that also need runfiles, you need to set
+    the right environment variables for them:
+
+      import subprocess
+      from bazel_tools.tools.python.runfiles import runfiles
+
+      r = runfiles.Create()
+      env = {}
+      ...
+      env.update(r.EnvVars())
+      p = subprocess.Popen([r.Rlocation("path/to/binary")], env, ...)
 """
 
 import os