path/filepath: document Clean behavior for each function

Document explicitly which functions Clean the result rather than
documenting it in the package comment.

Updates #10122.
Fixes #16111.

Change-Id: Ia589c7ee3936c9a6a758725ac7f143054d53e41e
Reviewed-on: https://go-review.googlesource.com/24747
Run-TryBot: Ian Lance Taylor <iant@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

src/path/filepath/path.go

@@ -4,9 +4,6 @@
 
 // Package filepath implements utility routines for manipulating filename paths
 // in a way compatible with the target operating system-defined file paths.
-//
-// Functions in this package replace any occurrences of the slash ('/') character
-// with os.PathSeparator when returning paths unless otherwise specified.
 package filepath
 
 import (
@@ -75,6 +72,8 @@ const (
 // The returned path ends in a slash only if it represents a root directory,
 // such as "/" on Unix or `C:\` on Windows.
 //
+// Finally, any occurrences of slash are replaced by Separator.
+//
 // If the result of this process is an empty string, Clean
 // returns the string ".".
 //
@@ -198,7 +197,7 @@ func Split(path string) (dir, file string) {
 }
 
 // Join joins any number of path elements into a single path, adding
-// a Separator if necessary. The result is Cleaned, in particular
+// a Separator if necessary. Join calls Clean on the result; in particular,
 // all empty strings are ignored.
 // On Windows, the result is a UNC path if and only if the first path
 // element is a UNC path.
@@ -223,6 +222,7 @@ func Ext(path string) string {
 // links.
 // If path is relative the result will be relative to the current directory,
 // unless one of the components is an absolute symbolic link.
+// EvalSymlinks call Clean on the result.
 func EvalSymlinks(path string) (string, error) {
 	return evalSymlinks(path)
 }
@@ -231,6 +231,7 @@ func EvalSymlinks(path string) (string, error) {
 // If the path is not absolute it will be joined with the current
 // working directory to turn it into an absolute path. The absolute
 // path name for a given file is not guaranteed to be unique.
+// Abs calls Clean on the result.
 func Abs(path string) (string, error) {
 	return abs(path)
 }
@@ -253,6 +254,7 @@ func unixAbs(path string) (string, error) {
 // 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)
@@ -442,7 +444,7 @@ func Base(path string) string {
 }
 
 // Dir returns all but the last element of path, typically the path's directory.
-// After dropping the final element, the path is Cleaned and trailing
+// After dropping the final element, Dir calls Clean on the path and trailing
 // slashes are removed.
 // If the path is empty, Dir returns ".".
 // If the path consists entirely of separators, Dir returns a single separator.