cmd/doc: document that json.Decode documents encoding/json.Decoder.Decode

Refine the documentation in cmd/doc and go help doc.

Fixes #12377.

Change-Id: I670c0a5cf18c9c9d5bb9bb222d8a3dd3722a3934
Reviewed-on: https://go-review.googlesource.com/14121
Reviewed-by: Andrew Gerrand <adg@golang.org>

src/cmd/doc/main.go

@@ -11,10 +11,12 @@
 // One argument:
 //	go doc <pkg>
 //	go doc <sym>[.<method>]
-//	go doc [<pkg>].<sym>[.<method>]
+//	go doc [<pkg>.]<sym>[.<method>]
+//	go doc [<pkg>.][<sym>.]<method>
 // The first item in this list that succeeds is the one whose documentation
 // is printed. If there is a symbol but no package, the package in the current
-// directory is chosen.
+// directory is chosen. However, if the argument begins with a capital
+// letter it is always assumed to be a symbol in the current directory.
 //
 // Two arguments:
 //	go doc <pkg> <sym>[.<method>]

src/cmd/go/alldocs.go

@@ -225,12 +225,15 @@ which is schematically one of these:
 
 	go doc <pkg>
 	go doc <sym>[.<method>]
-	go doc [<pkg>].<sym>[.<method>]
+	go doc [<pkg>.]<sym>[.<method>]
+	go doc [<pkg>.][<sym>.]<method>
 
-The first item in this list matched by the argument is the one whose
+The first item in this list matched by the argument is the one whose documentation
-documentation is printed. (See the examples below.) For packages, the order of
+is printed. (See the examples below.) However, if the argument starts with a capital
-scanning is determined lexically, but the GOROOT tree is always scanned before
+letter it is assumed to identify a symbol or method in the current directory.
-GOPATH.
+
+For packages, the order of scanning is determined lexically, but the GOROOT tree
+is always scanned before GOPATH.
 
 If there is no package specified or matched, the package in the current
 directory is selected, so "go doc Foo" shows the documentation for symbol Foo in
@@ -278,6 +281,14 @@ Examples:
 	go doc text/template new # Two arguments
 		Show documentation for text/template's New function.
 
+	At least in the current tree, these invocations all print the
+	documentation for json.Decoder's Decode method:
+
+	go doc json.Decoder.Decode
+	go doc json.decoder.decode
+	go doc json.decode
+	cd go/src/encoding/json; go doc decode
+
 Flags:
 	-c
 		Respect case when matching symbols.

src/cmd/go/doc.go

@@ -32,12 +32,15 @@ which is schematically one of these:
 
 	go doc <pkg>
 	go doc <sym>[.<method>]
-	go doc [<pkg>].<sym>[.<method>]
+	go doc [<pkg>.]<sym>[.<method>]
+	go doc [<pkg>.][<sym>.]<method>
 
-The first item in this list matched by the argument is the one whose
+The first item in this list matched by the argument is the one whose documentation
-documentation is printed. (See the examples below.) For packages, the order of
+is printed. (See the examples below.) However, if the argument starts with a capital
-scanning is determined lexically, but the GOROOT tree is always scanned before
+letter it is assumed to identify a symbol or method in the current directory.
-GOPATH.
+
+For packages, the order of scanning is determined lexically, but the GOROOT tree
+is always scanned before GOPATH.
 
 If there is no package specified or matched, the package in the current
 directory is selected, so "go doc Foo" shows the documentation for symbol Foo in
@@ -85,6 +88,14 @@ Examples:
 	go doc text/template new # Two arguments
 		Show documentation for text/template's New function.
 
+	At least in the current tree, these invocations all print the
+	documentation for json.Decoder's Decode method:
+
+	go doc json.Decoder.Decode
+	go doc json.decoder.decode
+	go doc json.decode
+	cd go/src/encoding/json; go doc decode
+
 Flags:
 	-c
 		Respect case when matching symbols.