path/filepath: steer people away from HasPrefix

The strikes against it are:

1. It does not take path boundaries into account.
2. It assumes that Windows==case-insensitive file system
and non-Windows==case-sensitive file system, neither of
which is always true.
3. Comparing ToLower against ToLower is not a correct
implementation of a case-insensitive string comparison.
4. If it returns true on Windows you still don't know how long
the matching prefix is in bytes, so you can't compute what
the suffix is.

R=golang-dev, r, dsymonds, r
CC=golang-dev
https://golang.org/cl/5712045

src/pkg/path/filepath/path_plan9.go

@@ -17,7 +17,7 @@ func VolumeName(path string) string {
 	return ""
 }
 
-// HasPrefix tests whether the path p begins with prefix.
+// HasPrefix exists for historical compatibility and should not be used.
 func HasPrefix(p, prefix string) bool {
 	return strings.HasPrefix(p, prefix)
 }

src/pkg/path/filepath/path_unix.go

@@ -19,7 +19,7 @@ func VolumeName(path string) string {
 	return ""
 }
 
-// HasPrefix tests whether the path p begins with prefix.
+// HasPrefix exists for historical compatibility and should not be used.
 func HasPrefix(p, prefix string) bool {
 	return strings.HasPrefix(p, prefix)
 }

src/pkg/path/filepath/path_windows.go

@@ -67,8 +67,7 @@ func VolumeName(path string) (v string) {
 	return ""
 }
 
-// HasPrefix tests whether the path p begins with prefix.
-// It ignores case while comparing.
+// HasPrefix exists for historical compatibility and should not be used.
 func HasPrefix(p, prefix string) bool {
 	if strings.HasPrefix(p, prefix) {
 		return true