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>

diff --git a/src/cmd/doc/main.go b/src/cmd/doc/main.go
index dda6aec22cdba68a88b95f8dc1c541875295232c..0985d95b60ac23a907c12a4f529ddde76cffb744 100644 (file)
--- a/src/cmd/doc/main.go
+++ b/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>]

diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go
index 941d4714095a86209c848debdf09d79cc3cd4b59..d11a5a00f7921e3c02c5085fa6ead4511ca45df6 100644 (file)
--- a/src/cmd/go/alldocs.go
+++ b/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
-documentation is printed. (See the examples below.) For packages, the order of
-scanning is determined lexically, but the GOROOT tree is always scanned before
-GOPATH.
+The first item in this list matched by the argument is the one whose documentation
+is printed. (See the examples below.) However, if the argument starts with a capital
+letter it is assumed to identify a symbol or method in the current directory.
+
+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.

diff --git a/src/cmd/go/doc.go b/src/cmd/go/doc.go
index 4a07dfe11f4e76a76a3aa6feceaa55c964ccf367..bed763679d2cca76804dfeb0f6af7f0451a93c2b 100644 (file)
--- a/src/cmd/go/doc.go
+++ b/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
-documentation is printed. (See the examples below.) For packages, the order of
-scanning is determined lexically, but the GOROOT tree is always scanned before
-GOPATH.
+The first item in this list matched by the argument is the one whose documentation
+is printed. (See the examples below.) However, if the argument starts with a capital
+letter it is assumed to identify a symbol or method in the current directory.
+
+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.