src/cmd/doc/main.go

// Copyright 2015 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

// Doc (usually run as go doc) accepts zero, one or two arguments.
//
// Zero arguments:
//	go doc
// Show the documentation for the package in the current directory.
//
// One argument:
//	go doc <pkg>
//	go doc <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.
//
// Two arguments:
//	go doc <pkg> <sym>[.<method>]
//
// Show the documentation for the package, symbol, and method. The
// first argument must be a full package path. This is similar to the
// command-line usage for the godoc command.
//
// For commands, unless the -cmd flag is present "go doc command"
// shows only the package-level docs for the package.
//
// For complete documentation, run "go help doc".
package main

import (
	"flag"
	"fmt"
	"go/build"
	"io"
	"log"
	"os"
	"path"
	"path/filepath"
	"strings"
	"unicode"
	"unicode/utf8"
)

var (
	unexported bool // -u flag
	matchCase  bool // -c flag
	showCmd    bool // -cmd flag
)

// usage is a replacement usage function for the flags package.
func usage() {
	fmt.Fprintf(os.Stderr, "Usage of [go] doc:\n")
	fmt.Fprintf(os.Stderr, "\tgo doc\n")
	fmt.Fprintf(os.Stderr, "\tgo doc <pkg>\n")
	fmt.Fprintf(os.Stderr, "\tgo doc <sym>[.<method>]\n")
	fmt.Fprintf(os.Stderr, "\tgo doc [<pkg>].<sym>[.<method>]\n")
	fmt.Fprintf(os.Stderr, "\tgo doc <pkg> <sym>[.<method>]\n")
	fmt.Fprintf(os.Stderr, "For more information run\n")
	fmt.Fprintf(os.Stderr, "\tgo help doc\n\n")
	fmt.Fprintf(os.Stderr, "Flags:\n")
	flag.PrintDefaults()
	os.Exit(2)
}

func main() {
	log.SetFlags(0)
	log.SetPrefix("doc: ")
	err := do(os.Stdout, flag.CommandLine, os.Args[1:])
	if err != nil {
		log.Fatal(err)
	}
}

// do is the workhorse, broken out of main to make testing easier.
func do(writer io.Writer, flagSet *flag.FlagSet, args []string) (err error) {
	flagSet.Usage = usage
	unexported = false
	matchCase = false
	flagSet.BoolVar(&unexported, "u", false, "show unexported symbols as well as exported")
	flagSet.BoolVar(&matchCase, "c", false, "symbol matching honors case (paths not affected)")
	flagSet.BoolVar(&showCmd, "cmd", false, "show symbols with package docs even if package is a command")
	flagSet.Parse(args)
	buildPackage, userPath, symbol := parseArgs(flagSet.Args())
	symbol, method := parseSymbol(symbol)
	pkg := parsePackage(writer, buildPackage, userPath)
	defer func() {
		pkg.flush()
		e := recover()
		if e == nil {
			return
		}
		pkgError, ok := e.(PackageError)
		if ok {
			err = pkgError
			return
		}
		panic(e)
	}()
	switch {
	case symbol == "":
		pkg.packageDoc()
		return
	case method == "":
		pkg.symbolDoc(symbol)
	default:
		pkg.methodDoc(symbol, method)
	}
	return nil
}

// parseArgs analyzes the arguments (if any) and returns the package
// it represents, the part of the argument the user used to identify
// the path (or "" if it's the current package) and the symbol
// (possibly with a .method) within that package.
// parseSymbol is used to analyze the symbol itself.
func parseArgs(args []string) (*build.Package, string, string) {
	switch len(args) {
	default:
		usage()
	case 0:
		// Easy: current directory.
		return importDir(pwd()), "", ""
	case 1:
		// Done below.
	case 2:
		// Package must be importable.
		pkg, err := build.Import(args[0], "", build.ImportComment)
		if err != nil {
			log.Fatalf("%s", err)
		}
		return pkg, args[0], args[1]
	}
	// Usual case: one argument.
	arg := args[0]
	// If it contains slashes, it begins with a package path.
	// First, is it a complete package path as it is? If so, we are done.
	// This avoids confusion over package paths that have other
	// package paths as their prefix.
	pkg, err := build.Import(arg, "", build.ImportComment)
	if err == nil {
		return pkg, arg, ""
	}
	// Another disambiguator: If the symbol starts with an upper
	// case letter, it can only be a symbol in the current directory.
	// Kills the problem caused by case-insensitive file systems
	// matching an upper case name as a package name.
	if isUpper(arg) {
		pkg, err := build.ImportDir(".", build.ImportComment)
		if err == nil {
			return pkg, "", arg
		}
	}
	// If it has a slash, it must be a package path but there is a symbol.
	// It's the last package path we care about.
	slash := strings.LastIndex(arg, "/")
	// There may be periods in the package path before or after the slash
	// and between a symbol and method.
	// Split the string at various periods to see what we find.
	// In general there may be ambiguities but this should almost always
	// work.
	var period int
	// slash+1: if there's no slash, the value is -1 and start is 0; otherwise
	// start is the byte after the slash.
	for start := slash + 1; start < len(arg); start = period + 1 {
		period = strings.Index(arg[start:], ".")
		symbol := ""
		if period < 0 {
			period = len(arg)
		} else {
			period += start
			symbol = arg[period+1:]
		}
		// Have we identified a package already?
		pkg, err := build.Import(arg[0:period], "", build.ImportComment)
		if err == nil {
			return pkg, arg[0:period], symbol
		}
		// See if we have the basename or tail of a package, as in json for encoding/json
		// or ivy/value for robpike.io/ivy/value.
		path := findPackage(arg[0:period])
		if path != "" {
			return importDir(path), arg[0:period], symbol
		}
	}
	// If it has a slash, we've failed.
	if slash >= 0 {
		log.Fatalf("no such package %s", arg[0:period])
	}
	// Guess it's a symbol in the current directory.
	return importDir(pwd()), "", arg
}

// importDir is just an error-catching wrapper for build.ImportDir.
func importDir(dir string) *build.Package {
	pkg, err := build.ImportDir(dir, build.ImportComment)
	if err != nil {
		log.Fatal(err)
	}
	return pkg
}

// parseSymbol breaks str apart into a symbol and method.
// Both may be missing or the method may be missing.
// If present, each must be a valid Go identifier.
func parseSymbol(str string) (symbol, method string) {
	if str == "" {
		return
	}
	elem := strings.Split(str, ".")
	switch len(elem) {
	case 1:
	case 2:
		method = elem[1]
		isIdentifier(method)
	default:
		log.Printf("too many periods in symbol specification")
		usage()
	}
	symbol = elem[0]
	isIdentifier(symbol)
	return
}

// isIdentifier checks that the name is valid Go identifier, and
// logs and exits if it is not.
func isIdentifier(name string) {
	if len(name) == 0 {
		log.Fatal("empty symbol")
	}
	for i, ch := range name {
		if unicode.IsLetter(ch) || ch == '_' || i > 0 && unicode.IsDigit(ch) {
			continue
		}
		log.Fatalf("invalid identifier %q", name)
	}
}

// isExported reports whether the name is an exported identifier.
// If the unexported flag (-u) is true, isExported returns true because
// it means that we treat the name as if it is exported.
func isExported(name string) bool {
	return unexported || isUpper(name)
}

// isUpper reports whether the name starts with an upper case letter.
func isUpper(name string) bool {
	ch, _ := utf8.DecodeRuneInString(name)
	return unicode.IsUpper(ch)
}

// findPackage returns the full file name path specified by the
// (perhaps partial) package path pkg.
func findPackage(pkg string) string {
	if pkg == "" {
		return ""
	}
	if isUpper(pkg) {
		return "" // Upper case symbol cannot be a package name.
	}
	path := pathFor(build.Default.GOROOT, pkg)
	if path != "" {
		return path
	}
	for _, root := range splitGopath() {
		path = pathFor(root, pkg)
		if path != "" {
			return path
		}
	}
	return ""
}

// splitGopath splits $GOPATH into a list of roots.
func splitGopath() []string {
	return filepath.SplitList(build.Default.GOPATH)
}

// pathsFor recursively walks the tree at root looking for possible directories for the package:
// those whose package path is pkg or which have a proper suffix pkg.
func pathFor(root, pkg string) (result string) {
	root = path.Join(root, "src")
	slashDot := string(filepath.Separator) + "."
	// We put a slash on the pkg so can use simple string comparison below
	// yet avoid inadvertent matches, like /foobar matching bar.
	pkgString := filepath.Clean(string(filepath.Separator) + pkg)

	// We use panic/defer to short-circuit processing at the first match.
	// A nil panic reports that the path has been found.
	defer func() {
		err := recover()
		if err != nil {
			panic(err)
		}
	}()

	visit := func(pathName string, f os.FileInfo, err error) error {
		if err != nil {
			return nil
		}
		// One package per directory. Ignore the files themselves.
		if !f.IsDir() {
			return nil
		}
		// No .git or other dot nonsense please.
		if strings.Contains(pathName, slashDot) {
			return filepath.SkipDir
		}
		// Is the tail of the path correct?
		if strings.HasSuffix(pathName, pkgString) && hasGoFiles(pathName) {
			result = pathName
			panic(nil)
		}
		return nil
	}

	filepath.Walk(root, visit)
	return "" // Call to panic above sets the real value.
}

// hasGoFiles tests whether the directory contains at least one file with ".go"
// extension
func hasGoFiles(path string) bool {
	dir, err := os.Open(path)
	if err != nil {
		// ignore unreadable directories
		return false
	}
	defer dir.Close()

	names, err := dir.Readdirnames(0)
	if err != nil {
		// ignore unreadable directories
		return false
	}

	for _, name := range names {
		if strings.HasSuffix(name, ".go") {
			return true
		}
	}

	return false
}

// pwd returns the current directory.
func pwd() string {
	wd, err := os.Getwd()
	if err != nil {
		log.Fatal(err)
	}
	return wd
}