os: recomment MkdirAll

The internal comments are not completely precise about
what is going on, and they are causing confusion.

Fixes #8283.

LGTM=r
R=r
CC=golang-codereviews
https://golang.org/cl/151460043

diff --git a/src/os/path.go b/src/os/path.go
index 24a3415b4660b7e0ab0f1e54c83fcb0d19a73a6e..84a3be3348f1d82e28790a4d005c857fce938ee0 100644 (file)
--- a/src/os/path.go
+++ b/src/os/path.go
@@ -17,7 +17,7 @@ import (
 // If path is already a directory, MkdirAll does nothing
 // and returns nil.
 func MkdirAll(path string, perm FileMode) error {
-       // If path exists, stop with success or error.
+       // Fast path: if we can tell whether path is a directory or file, stop with success or error.
        dir, err := Stat(path)
        if err == nil {
                if dir.IsDir() {
@@ -26,7 +26,7 @@ func MkdirAll(path string, perm FileMode) error {
                return &PathError{"mkdir", path, syscall.ENOTDIR}
        }
 
-       // Doesn't already exist; make sure parent does.
+       // Slow path: make sure parent exists and then call Mkdir for path.
        i := len(path)
        for i > 0 && IsPathSeparator(path[i-1]) { // Skip trailing path separator.
                i--
@@ -45,7 +45,7 @@ func MkdirAll(path string, perm FileMode) error {
                }
        }
 
-       // Now parent exists, try to create.
+       // Parent now exists; invoke Mkdir and use its result.
        err = Mkdir(path, perm)
        if err != nil {
                // Handle arguments like "foo/." by