godoc: make godoc go work

- if a package path leads to subdirectories only,
  show command instead, if any
- to force documentation for a command, use the
  cmd/ prefix, as in: godoc cmd/go
  (note that for the go command, the prefix is
  not required since there is no actual go library
  package at the moment)

Fixes #3012.

R=rsc
CC=golang-dev
https://golang.org/cl/5665049

diff --git a/src/cmd/godoc/doc.go b/src/cmd/godoc/doc.go
index 3fad1b0d66bc039c774f942fc3977aee2b4d27ec..15c393cd761449e12fccd776652e2447d739f748 100644 (file)
--- a/src/cmd/godoc/doc.go
+++ b/src/cmd/godoc/doc.go
@@ -9,12 +9,15 @@ Godoc extracts and generates documentation for Go programs.
 It has two modes.
 
 Without the -http flag, it runs in command-line mode and prints plain text
-documentation to standard output and exits. If the -src flag is specified,
-godoc prints the exported interface of a package in Go source form, or the
-implementation of a specific exported language entity:
+documentation to standard output and exits. If both a library package and
+a command with the same name exists, using the prefix cmd/ will force
+documentation on the command rather than the library package. If the -src
+flag is specified, godoc prints the exported interface of a package in Go
+source form, or the implementation of a specific exported language entity:
 
        godoc fmt                # documentation for package fmt
        godoc fmt Printf         # documentation for fmt.Printf
+       godoc cmd/go             # force documentation for the go command
        godoc -src fmt           # fmt package interface in Go source form
        godoc -src fmt Printf    # implementation of fmt.Printf
 

diff --git a/src/cmd/godoc/main.go b/src/cmd/godoc/main.go
index f74b6f40475ef073c2c5440f86afd706eac6d55b..e5e81c6dfa19b63a7a5e1b3c19ae648ba2feb078 100644 (file)
--- a/src/cmd/godoc/main.go
+++ b/src/cmd/godoc/main.go
@@ -374,11 +374,16 @@ func main() {
        }
 
        // determine paths
+       const cmdPrefix = "cmd/"
        path := flag.Arg(0)
-       if len(path) > 0 && path[0] == '.' {
+       var forceCmd bool
+       if strings.HasPrefix(path, ".") {
                // assume cwd; don't assume -goroot
                cwd, _ := os.Getwd() // ignore errors
                path = filepath.Join(cwd, path)
+       } else if strings.HasPrefix(path, cmdPrefix) {
+               path = path[len(cmdPrefix):]
+               forceCmd = true
        }
        relpath := path
        abspath := path
@@ -393,6 +398,7 @@ func main() {
 
        var mode PageInfoMode
        if relpath == builtinPkgPath {
+               // the fake built-in package contains unexported identifiers
                mode = noFiltering
        }
        if *srcMode {
@@ -404,20 +410,35 @@ func main() {
        }
        // TODO(gri): Provide a mechanism (flag?) to select a package
        //            if there are multiple packages in a directory.
-       info := pkgHandler.getPageInfo(abspath, relpath, "", mode)
 
+       // first, try as package unless forced as command
+       var info PageInfo
+       if !forceCmd {
+               info = pkgHandler.getPageInfo(abspath, relpath, "", mode)
+       }
+
+       // second, try as command
+       if !filepath.IsAbs(path) {
+               abspath = absolutePath(path, cmdHandler.fsRoot)
+       }
+       cinfo := cmdHandler.getPageInfo(abspath, relpath, "", mode)
+
+       // determine what to use
        if info.IsEmpty() {
-               // try again, this time assume it's a command
-               if !filepath.IsAbs(path) {
-                       abspath = absolutePath(path, cmdHandler.fsRoot)
+               if !cinfo.IsEmpty() {
+                       // only cinfo exists - switch to cinfo
+                       info = cinfo
                }
-               cmdInfo := cmdHandler.getPageInfo(abspath, relpath, "", mode)
-               // only use the cmdInfo if it actually contains a result
-               // (don't hide errors reported from looking up a package)
-               if !cmdInfo.IsEmpty() {
-                       info = cmdInfo
+       } else if !cinfo.IsEmpty() {
+               // both info and cinfo exist - use cinfo if info
+               // contains only subdirectory information
+               if info.PAst == nil && info.PDoc == nil {
+                       info = cinfo
+               } else {
+                       fmt.Printf("use 'godoc %s%s' for documentation on the %s command \n\n", cmdPrefix, relpath, relpath)
                }
        }
+
        if info.Err != nil {
                log.Fatalf("%v", info.Err)
        }