path/filepath: reword documentation for Rel

The existing func Rel's API documentation was presented in a rather
dense way without a lot of organization that oriented around topical
flow, so the documentation has been cleaned up to present the
function's behavior more clearly and concisely.

Fixes #75893

Change-Id: I6c8f6ef508250397be9d0127a15508e7335f18c4
Reviewed-on: https://go-review.googlesource.com/c/go/+/712440
Reviewed-by: David Chase <drchase@google.com>
Auto-Submit: Dmitri Shuralyov <dmitshur@golang.org>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
TryBot-Bypass: Dmitri Shuralyov <dmitshur@golang.org>
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>

Author: matttproud

src/path/filepath/path.go

@@ -173,19 +173,20 @@ func unixAbs(path string) (string, error) {
 	return Join(wd, path), nil
 }
 
-// Rel returns a relative path that is lexically equivalent to targpath when
-// joined to basepath with an intervening separator. That is,
-// [Join](basepath, Rel(basepath, targpath)) is equivalent to targpath itself.
-// On success, the returned path will always be relative to basepath,
-// even if basepath and targpath share no elements.
-// An error is returned if targpath can't be made relative to basepath or if
-// knowing the current working directory would be necessary to compute it.
-// Rel calls [Clean] on the result.
-func Rel(basepath, targpath string) (string, error) {
-	baseVol := VolumeName(basepath)
-	targVol := VolumeName(targpath)
-	base := Clean(basepath)
-	targ := Clean(targpath)
+// Rel returns a relative path that is lexically equivalent to targPath when
+// joined to basePath with an intervening separator. That is,
+// [Join](basePath, Rel(basePath, targPath)) is equivalent to targPath itself.
+//
+// The returned path will always be relative to basePath, even if basePath and
+// targPath share no elements. Rel calls [Clean] on the result.
+//
+// An error is returned if targPath can't be made relative to basePath
+// or if knowing the current working directory would be necessary to compute it.
+func Rel(basePath, targPath string) (string, error) {
+	baseVol := VolumeName(basePath)
+	targVol := VolumeName(targPath)
+	base := Clean(basePath)
+	targ := Clean(targPath)
 	if sameWord(targ, base) {
 		return ".", nil
 	}
@@ -194,15 +195,15 @@ func Rel(basepath, targpath string) (string, error) {
 	if base == "." {
 		base = ""
 	} else if base == "" && filepathlite.VolumeNameLen(baseVol) > 2 /* isUNC */ {
-		// Treat any targetpath matching `\\host\share` basepath as absolute path.
+		// Treat any targetpath matching `\\host\share` basePath as absolute path.
 		base = string(Separator)
 	}
 
 	// Can't use IsAbs - `\a` and `a` are both relative in Windows.
 	baseSlashed := len(base) > 0 && base[0] == Separator
 	targSlashed := len(targ) > 0 && targ[0] == Separator
 	if baseSlashed != targSlashed || !sameWord(baseVol, targVol) {
-		return "", errors.New("Rel: can't make " + targpath + " relative to " + basepath)
+		return "", errors.New("Rel: can't make " + targPath + " relative to " + basePath)
 	}
 	// Position base[b0:bi] and targ[t0:ti] at the first differing elements.
 	bl := len(base)
@@ -228,7 +229,7 @@ func Rel(basepath, targpath string) (string, error) {
 		t0 = ti
 	}
 	if base[b0:bi] == ".." {
-		return "", errors.New("Rel: can't make " + targpath + " relative to " + basepath)
+		return "", errors.New("Rel: can't make " + targPath + " relative to " + basePath)
 	}
 	if b0 != bl {
 		// Base elements left. Must go up before going down.