Clarify the various directories that make Bazel work.

 - expand descriptions
 - include example paths
 - show how to find the exact paths
 - clean out some old TODOs

PiperOrigin-RevId: 435341037

src/main/java/com/google/devtools/build/lib/analysis/BlazeDirectories.java

@@ -28,14 +28,37 @@
 /**
  * Encapsulates the directories related to a workspace.
  *
- * <p>The <code>workspace</code> is the top-level directory in the user's client (possibly
- * read-only). The <code>execRoot</code> is the working directory for all spawned tools, which is
- * generally below the <code>outputBase</code>.
+ * <p>A {@code workspace>} is a directory tree containing the source files you want to build.
  *
- * <p>Care must be taken to avoid multiple Bazel instances trying to write to the same output
- * directory. At this time, this is enforced by requiring a 1:1 correspondence between a running
- * Bazel instance and an output base directory, though this requirement may be softened in the
- * future.
+ * <p>The {@code workspace Path} object this class stores is the workspace's root directory, which
+ * contains a {@code WORKSPACE} file that marks and configures the workspace. When you build {@code
+ * //my:project}, this signifies a target named {@code project} in a {@code BUILD} file in the
+ * {@code my} subdirectory under the workspace root. You can find the workspace root directory by
+ * running {@code $ bazel info | grep workspace}.
+ *
+ * <p>The {@code outputBase} is where all workspace output is written. This includes both build
+ * outputs and internal files Bazel uses to support builds (like the action cache, log files, and
+ * external repository mappings). This path is only meaningful for core Bazel devs: it's not part of
+ * the public user API. This path is not under the workspace root (since its purpose isn't to host
+ * workspace source files). This appears as {@code _bazel_$USER/$SOME_HASH/} under some local file
+ * system root. Exact paths vary depending on what machine you're running Bazel on. You can find
+ * this path by running {@code $ bazel info | grep output_base}.
+ *
+ * <p>The {@code execRoot} is the working directory for all spawned tools. It includes both the
+ * subdirectory where Bazel writes build outputs (the {@code outputPath}) and the symlink forest
+ * Bazel constructs to map workspace source files the spawned tool can access when it runs. It
+ * generally looks like {@code $OUTPUT_BASE/execroot/$WORKSPACE_IDENTIFIER}. You can find this path
+ * by running {@code $ bazel info | grep execution_root}.
+ *
+ * <p>The {@code outputPath} (confusingly similar name to {@code outputBase}, alas) is the root path
+ * where Bazel writes build outputs. In other words, any action transforming a source file into a
+ * generated output writes that output under this path. It generally looks like {@code
+ * $OUTPUT_BASE/execroot/$WORKSPACE_IDENTIFIER/bazel-out}. You can find this path by running {@code
+ * $ bazel info | grep output_path}.
+ *
+ * <p>Care must be taken to avoid multiple Bazel instances trying to write to the same output tree.
+ * This is enforced by requiring a 1:1 correspondence between a running Bazel instance and an output
+ * base.
  *
  * <p>If the user does not qualify an output base directory, the startup code will derive it
  * deterministically from the workspace. Note also that while the Bazel server process runs with the
@@ -227,6 +250,11 @@ public HashCode getInstallMD5() {
     return serverDirectories.getInstallMD5();
   }
 
+  /**
+   * Returns the directory where Bazel writes build outputs, relative to the execRoot.
+   *
+   * <p>For example: {@code "bazel-out"}.
+   */
   public String getRelativeOutputPath() {
     return BlazeDirectories.getRelativeOutputPath(productName);
   }
@@ -236,8 +264,9 @@ public String getProductName() {
   }
 
   /**
-   * Returns the output directory name, relative to the execRoot. TODO(bazel-team): (2011) make this
-   * private?
+   * Returns the directory where Bazel writes build outputs, relative to the execRoot.
+   *
+   * <p>For example: {@code "bazel-out"}.
    */
   public static String getRelativeOutputPath(String productName) {
     return StringCanonicalizer.intern(productName + "-out");