path/filepath: clarify the package doc about '/' in returned results.

The slash is replaced with os.PathSeparator before returning.
Split, SplitList are the exceptions; comments for them mention this.

Fixes golang/go#10122.

Change-Id: I66dbee8d09f378582e046be8df309a3930151820
Reviewed-on: https://go-review.googlesource.com/7310Reviewed-by: Alex Brainman <alex.brainman@gmail.com>
Reviewed-by: Rob Pike <r@golang.org>

src/path/filepath/path.go

@@ -4,6 +4,9 @@
 
 // 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 (
@@ -174,7 +177,8 @@ func FromSlash(path string) string {
 
 // SplitList splits a list of paths joined by the OS-specific ListSeparator,
 // usually found in PATH or GOPATH environment variables.
-// Unlike strings.Split, SplitList returns an empty slice when passed an empty string.
+// Unlike strings.Split, SplitList returns an empty slice when passed an empty
+// string. SplitList does not replace slash characters in the returned paths.
 func SplitList(path string) []string {
 	return splitList(path)
 }