[7.1.0] Improve the documentation for PathFragment methods dealing wi…

…th segments. (#21275)

PiperOrigin-RevId: 605614626
Change-Id: I1db0c8a7c8b6262e55509c599a9ca3d39e292019

src/main/java/com/google/devtools/build/lib/vfs/PathFragment.java

@@ -420,7 +420,7 @@ public int compareTo(PathFragment o) {
   ////////////////////////////////////////////////////////////////////////
 
   /**
-   * Returns the number of segments in this path.
+   * Returns the number of segments in this path, excluding the drive string for absolute paths.
    *
    * <p>This operation is O(N) on the length of the string.
    */
@@ -500,6 +500,10 @@ public String getSegment(int index) {
    * </code>. Thus the number of segments in the new PathFragment is <code>endIndex - beginIndex
    * </code>.
    *
+   * <p>If the path is absolute and <code>beginIndex</code> is zero, the returned path is absolute.
+   * Otherwise, if the path is relative or <code>beginIndex> is greater than zero, the returned path
+   * is relative.
+   *
    * <p>This operation is O(N) on the length of the string.
    *
    * @param beginIndex the beginning index, inclusive.
@@ -556,7 +560,7 @@ private PathFragment subFragmentImpl(int beginIndex, int endIndex) {
       throw new IndexOutOfBoundsException(
           String.format("path: %s, beginIndex: %d endIndex: %d", toString(), beginIndex, endIndex));
     }
-    // If beginIndex is 0 we include the drive. Very odd semantics.
+    // If beginIndex is 0, we include the drive string.
     int driveStrLength = 0;
     if (beginIndex == 0) {
       starti = 0;