3 files changed, 20 insertions, 10 deletions
diff --git a/src/pkg/path/filepath/match.go b/src/pkg/path/filepath/match.go
index c3678f541d..38d264fb97 100644
--- a/src/pkg/path/filepath/match.go
+++ b/src/pkg/path/filepath/match.go
@@ -12,6 +12,7 @@ import (
 	"unicode/utf8"
 )
 
+// ErrBadPattern indicates a globbing pattern was malformed.
 var ErrBadPattern = errors.New("syntax error in pattern")
 
 // Match returns true if name matches the shell file name pattern.
@@ -33,7 +34,8 @@ var ErrBadPattern = errors.New("syntax error in pattern")
 //		lo '-' hi   matches character c for lo <= c <= hi
 //
 // Match requires pattern to match all of name, not just a substring.
-// The only possible error return occurs when the pattern is malformed.
+// The only possible returned error is ErrBadPattern, when pattern
+// is malformed.
 //
 func Match(pattern, name string) (matched bool, err error) {
 Pattern:
@@ -211,7 +213,6 @@ func getEsc(chunk string) (r rune, nchunk string, err error) {
 // if there is no matching file. The syntax of patterns is the same
 // as in Match. The pattern may describe hierarchical names such as
 // /usr/*/bin/ed (assuming the Separator is '/').
-// The only possible error return occurs when the pattern is malformed.
 //
 func Glob(pattern string) (matches []string, err error) {
 	if !hasMeta(pattern) {
@@ -253,7 +254,6 @@ func Glob(pattern string) (matches []string, err error) {
 // and appends them to matches. If the directory cannot be
 // opened, it returns the existing matches. New matches are
 // added in lexicographical order.
-// The only possible error return occurs when the pattern is malformed.
 func glob(dir, pattern string, matches []string) (m []string, e error) {
 	m = matches
 	fi, err := os.Stat(dir)
diff --git a/src/pkg/path/filepath/path.go b/src/pkg/path/filepath/path.go
index 3dc52aab46..f468d33264 100644
--- a/src/pkg/path/filepath/path.go
+++ b/src/pkg/path/filepath/path.go
@@ -36,7 +36,7 @@ const (
 // returns the string ".".
 //
 // See also Rob Pike, ``Lexical File Names in Plan 9 or
-// Getting Dot-Dot right,''
+// Getting Dot-Dot Right,''
 // http://plan9.bell-labs.com/sys/doc/lexnames.html
 func Clean(path string) string {
 	vol := VolumeName(path)
@@ -118,7 +118,8 @@ func Clean(path string) string {
 }
 
 // ToSlash returns the result of replacing each separator character
-// in path with a slash ('/') character.
+// in path with a slash ('/') character. Multiple separators are
+// replaced by multiple slashes.
 func ToSlash(path string) string {
 	if Separator == '/' {
 		return path
@@ -127,7 +128,8 @@ func ToSlash(path string) string {
 }
 
 // FromSlash returns the result of replacing each slash ('/') character
-// in path with a separator character.
+// in path with a separator character. Multiple slashes are replaced
+// by multiple separators.
 func FromSlash(path string) string {
 	if Separator == '/' {
 		return path
@@ -135,7 +137,8 @@ func FromSlash(path string) string {
 	return strings.Replace(path, "/", string(Separator), -1)
 }
 
-// SplitList splits a list of paths joined by the OS-specific ListSeparator.
+// SplitList splits a list of paths joined by the OS-specific ListSeparator,
+// usually found in PATH or GOPATH environment variables.
 func SplitList(path string) []string {
 	if path == "" {
 		return []string{}
@@ -158,7 +161,8 @@ func Split(path string) (dir, file string) {
 }
 
 // Join joins any number of path elements into a single path, adding
-// a Separator if necessary.  All empty strings are ignored.
+// a Separator if necessary. The result is Cleaned, in particular
+// all empty strings are ignored.
 func Join(elem ...string) string {
 	for i, e := range elem {
 		if e != "" {
@@ -183,7 +187,8 @@ func Ext(path string) string {
 
 // EvalSymlinks returns the path name after the evaluation of any symbolic
 // links.
-// If path is relative it will be evaluated relative to the current directory.
+// If path is relative the result will be relative to the current directory,
+// unless one of the components is an absolute symbolic link.
 func EvalSymlinks(path string) (string, error) {
 	if runtime.GOOS == "windows" {
 		// Symlinks are not supported under windows.
@@ -443,7 +448,7 @@ func Base(path string) string {
 	return path
 }
 
-// Dir returns the all but the last element of path, typically the path's directory.
+// Dir returns all but the last element of path, typically the path's directory.
 // Trailing path separators are removed before processing.
 // If the path is empty, Dir returns ".".
 // If the path consists entirely of separators, Dir returns a single separator.
diff --git a/src/pkg/path/filepath/path_test.go b/src/pkg/path/filepath/path_test.go
index 4572707ace..6b70aa2cd7 100644
--- a/src/pkg/path/filepath/path_test.go
+++ b/src/pkg/path/filepath/path_test.go
@@ -559,6 +559,7 @@ var EvalSymlinksTestDirs = []EvalSymlinksTest{
 	{"test/dir/link3", "../../"},
 	{"test/link1", "../test"},
 	{"test/link2", "dir"},
+	{"test/linkabs", "/tmp"},
 }
 
 var EvalSymlinksTests = []EvalSymlinksTest{
@@ -571,6 +572,7 @@ var EvalSymlinksTests = []EvalSymlinksTest{
 	{"test/link2/..", "test"},
 	{"test/dir/link3", "."},
 	{"test/link2/link3/test", "test"},
+	{"test/linkabs", "/tmp"},
 }
 
 var EvalSymlinksAbsWindowsTests = []EvalSymlinksTest{
@@ -629,6 +631,9 @@ func TestEvalSymlinks(t *testing.T) {
 	for _, d := range tests {
 		path := simpleJoin(tmpDir, d.path)
 		dest := simpleJoin(tmpDir, d.dest)
+		if filepath.IsAbs(d.dest) {
+			dest = d.dest
+		}
 		if p, err := filepath.EvalSymlinks(path); err != nil {
 			t.Errorf("EvalSymlinks(%q) error: %v", d.path, err)
 		} else if filepath.Clean(p) != filepath.Clean(dest) {