blob: defddfd74a6b9ccd2c2b34ce8e401afe33ca503b [file] [log] [blame]
// 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.
package main
import (
"bytes"
"fmt"
"go/ast"
"go/build"
"go/doc"
"go/format"
"go/parser"
"go/token"
"io"
"log"
"os"
"path/filepath"
"strings"
"unicode"
"unicode/utf8"
)
const (
punchedCardWidth = 80 // These things just won't leave us alone.
indentedWidth = punchedCardWidth - len(indent)
indent = " "
)
type Package struct {
writer io.Writer // Destination for output.
name string // Package name, json for encoding/json.
userPath string // String the user used to find this package.
pkg *ast.Package // Parsed package.
file *ast.File // Merged from all files in the package
doc *doc.Package
build *build.Package
fs *token.FileSet // Needed for printing.
buf bytes.Buffer
}
type PackageError string // type returned by pkg.Fatalf.
func (p PackageError) Error() string {
return string(p)
}
// prettyPath returns a version of the package path that is suitable for an
// error message. It obeys the import comment if present. Also, since
// pkg.build.ImportPath is sometimes the unhelpful "" or ".", it looks for a
// directory name in GOROOT or GOPATH if that happens.
func (pkg *Package) prettyPath() string {
path := pkg.build.ImportComment
if path == "" {
path = pkg.build.ImportPath
}
if path != "." && path != "" {
return path
}
// Convert the source directory into a more useful path.
// Also convert everything to slash-separated paths for uniform handling.
path = filepath.Clean(filepath.ToSlash(pkg.build.Dir))
// Can we find a decent prefix?
goroot := filepath.Join(build.Default.GOROOT, "src")
if p, ok := trim(path, filepath.ToSlash(goroot)); ok {
return p
}
for _, gopath := range splitGopath() {
if p, ok := trim(path, filepath.ToSlash(gopath)); ok {
return p
}
}
return path
}
// trim trims the directory prefix from the path, paying attention
// to the path separator. If they are the same string or the prefix
// is not present the original is returned. The boolean reports whether
// the prefix is present. That path and prefix have slashes for separators.
func trim(path, prefix string) (string, bool) {
if !strings.HasPrefix(path, prefix) {
return path, false
}
if path == prefix {
return path, true
}
if path[len(prefix)] == '/' {
return path[len(prefix)+1:], true
}
return path, false // Textual prefix but not a path prefix.
}
// pkg.Fatalf is like log.Fatalf, but panics so it can be recovered in the
// main do function, so it doesn't cause an exit. Allows testing to work
// without running a subprocess. The log prefix will be added when
// logged in main; it is not added here.
func (pkg *Package) Fatalf(format string, args ...interface{}) {
panic(PackageError(fmt.Sprintf(format, args...)))
}
// parsePackage turns the build package we found into a parsed package
// we can then use to generate documentation.
func parsePackage(writer io.Writer, pkg *build.Package, userPath string) *Package {
fs := token.NewFileSet()
// include tells parser.ParseDir which files to include.
// That means the file must be in the build package's GoFiles or CgoFiles
// list only (no tag-ignored files, tests, swig or other non-Go files).
include := func(info os.FileInfo) bool {
for _, name := range pkg.GoFiles {
if name == info.Name() {
return true
}
}
for _, name := range pkg.CgoFiles {
if name == info.Name() {
return true
}
}
return false
}
pkgs, err := parser.ParseDir(fs, pkg.Dir, include, parser.ParseComments)
if err != nil {
log.Fatal(err)
}
// Make sure they are all in one package.
if len(pkgs) != 1 {
log.Fatalf("multiple packages in directory %s", pkg.Dir)
}
astPkg := pkgs[pkg.Name]
// TODO: go/doc does not include typed constants in the constants
// list, which is what we want. For instance, time.Sunday is of type
// time.Weekday, so it is defined in the type but not in the
// Consts list for the package. This prevents
// go doc time.Sunday
// from finding the symbol. Work around this for now, but we
// should fix it in go/doc.
// A similar story applies to factory functions.
docPkg := doc.New(astPkg, pkg.ImportPath, doc.AllDecls)
for _, typ := range docPkg.Types {
docPkg.Consts = append(docPkg.Consts, typ.Consts...)
docPkg.Vars = append(docPkg.Vars, typ.Vars...)
docPkg.Funcs = append(docPkg.Funcs, typ.Funcs...)
}
return &Package{
writer: writer,
name: pkg.Name,
userPath: userPath,
pkg: astPkg,
file: ast.MergePackageFiles(astPkg, 0),
doc: docPkg,
build: pkg,
fs: fs,
}
}
func (pkg *Package) Printf(format string, args ...interface{}) {
fmt.Fprintf(&pkg.buf, format, args...)
}
func (pkg *Package) flush() {
_, err := pkg.writer.Write(pkg.buf.Bytes())
if err != nil {
log.Fatal(err)
}
pkg.buf.Reset() // Not needed, but it's a flush.
}
var newlineBytes = []byte("\n\n") // We never ask for more than 2.
// newlines guarantees there are n newlines at the end of the buffer.
func (pkg *Package) newlines(n int) {
for !bytes.HasSuffix(pkg.buf.Bytes(), newlineBytes[:n]) {
pkg.buf.WriteRune('\n')
}
}
// emit prints the node.
func (pkg *Package) emit(comment string, node ast.Node) {
if node != nil {
err := format.Node(&pkg.buf, pkg.fs, node)
if err != nil {
log.Fatal(err)
}
if comment != "" {
pkg.newlines(1)
doc.ToText(&pkg.buf, comment, " ", indent, indentedWidth)
pkg.newlines(2) // Blank line after comment to separate from next item.
} else {
pkg.newlines(1)
}
}
}
var formatBuf bytes.Buffer // Reusable to avoid allocation.
// formatNode is a helper function for printing.
func (pkg *Package) formatNode(node ast.Node) []byte {
formatBuf.Reset()
format.Node(&formatBuf, pkg.fs, node)
return formatBuf.Bytes()
}
// oneLineFunc prints a function declaration as a single line.
func (pkg *Package) oneLineFunc(decl *ast.FuncDecl) {
decl.Doc = nil
decl.Body = nil
pkg.emit("", decl)
}
// oneLineValueGenDecl prints a var or const declaration as a single line.
func (pkg *Package) oneLineValueGenDecl(decl *ast.GenDecl) {
decl.Doc = nil
dotDotDot := ""
if len(decl.Specs) > 1 {
dotDotDot = " ..."
}
// Find the first relevant spec.
for i, spec := range decl.Specs {
valueSpec := spec.(*ast.ValueSpec) // Must succeed; we can't mix types in one genDecl.
if !isExported(valueSpec.Names[0].Name) {
continue
}
typ := ""
if valueSpec.Type != nil {
typ = fmt.Sprintf(" %s", pkg.formatNode(valueSpec.Type))
}
val := ""
if i < len(valueSpec.Values) && valueSpec.Values[i] != nil {
val = fmt.Sprintf(" = %s", pkg.formatNode(valueSpec.Values[i]))
}
pkg.Printf("%s %s%s%s%s\n", decl.Tok, valueSpec.Names[0], typ, val, dotDotDot)
break
}
}
// oneLineTypeDecl prints a type declaration as a single line.
func (pkg *Package) oneLineTypeDecl(spec *ast.TypeSpec) {
spec.Doc = nil
spec.Comment = nil
switch spec.Type.(type) {
case *ast.InterfaceType:
pkg.Printf("type %s interface { ... }\n", spec.Name)
case *ast.StructType:
pkg.Printf("type %s struct { ... }\n", spec.Name)
default:
pkg.Printf("type %s %s\n", spec.Name, pkg.formatNode(spec.Type))
}
}
// packageDoc prints the docs for the package (package doc plus one-liners of the rest).
func (pkg *Package) packageDoc() {
defer pkg.flush()
if pkg.showInternals() {
pkg.packageClause(false)
}
doc.ToText(&pkg.buf, pkg.doc.Doc, "", indent, indentedWidth)
pkg.newlines(1)
if !pkg.showInternals() {
// Show only package docs for commands.
return
}
pkg.newlines(2) // Guarantee blank line before the components.
pkg.valueSummary(pkg.doc.Consts)
pkg.valueSummary(pkg.doc.Vars)
pkg.funcSummary(pkg.doc.Funcs, false)
pkg.typeSummary()
pkg.bugs()
}
// showInternals reports whether we should show the internals
// of a package as opposed to just the package docs.
// Used to decide whether to suppress internals for commands.
// Called only by Package.packageDoc.
func (pkg *Package) showInternals() bool {
return pkg.pkg.Name != "main" || showCmd
}
// packageClause prints the package clause.
// The argument boolean, if true, suppresses the output if the
// user's argument is identical to the actual package path or
// is empty, meaning it's the current directory.
func (pkg *Package) packageClause(checkUserPath bool) {
if checkUserPath {
if pkg.userPath == "" || pkg.userPath == pkg.build.ImportPath {
return
}
}
importPath := pkg.build.ImportComment
if importPath == "" {
importPath = pkg.build.ImportPath
}
pkg.Printf("package %s // import %q\n\n", pkg.name, importPath)
if importPath != pkg.build.ImportPath {
pkg.Printf("WARNING: package source is installed in %q\n", pkg.build.ImportPath)
}
}
// valueSummary prints a one-line summary for each set of values and constants.
func (pkg *Package) valueSummary(values []*doc.Value) {
for _, value := range values {
pkg.oneLineValueGenDecl(value.Decl)
}
}
// funcSummary prints a one-line summary for each function. Constructors
// are printed by typeSummary, below, and so can be suppressed here.
func (pkg *Package) funcSummary(funcs []*doc.Func, showConstructors bool) {
// First, identify the constructors. Don't bother figuring out if they're exported.
var isConstructor map[*doc.Func]bool
if !showConstructors {
isConstructor = make(map[*doc.Func]bool)
for _, typ := range pkg.doc.Types {
for _, constructor := range typ.Funcs {
if isExported(typ.Name) {
isConstructor[constructor] = true
}
}
}
}
for _, fun := range funcs {
decl := fun.Decl
// Exported functions only. The go/doc package does not include methods here.
if isExported(fun.Name) {
if !isConstructor[fun] {
pkg.oneLineFunc(decl)
}
}
}
}
// typeSummary prints a one-line summary for each type, followed by its constructors.
func (pkg *Package) typeSummary() {
for _, typ := range pkg.doc.Types {
for _, spec := range typ.Decl.Specs {
typeSpec := spec.(*ast.TypeSpec) // Must succeed.
if isExported(typeSpec.Name.Name) {
pkg.oneLineTypeDecl(typeSpec)
// Now print the constructors.
for _, constructor := range typ.Funcs {
if isExported(constructor.Name) {
pkg.Printf(indent)
pkg.oneLineFunc(constructor.Decl)
}
}
}
}
}
}
// bugs prints the BUGS information for the package.
// TODO: Provide access to TODOs and NOTEs as well (very noisy so off by default)?
func (pkg *Package) bugs() {
if pkg.doc.Notes["BUG"] == nil {
return
}
pkg.Printf("\n")
for _, note := range pkg.doc.Notes["BUG"] {
pkg.Printf("%s: %v\n", "BUG", note.Body)
}
}
// findValues finds the doc.Values that describe the symbol.
func (pkg *Package) findValues(symbol string, docValues []*doc.Value) (values []*doc.Value) {
for _, value := range docValues {
for _, name := range value.Names {
if match(symbol, name) {
values = append(values, value)
}
}
}
return
}
// findFuncs finds the doc.Funcs that describes the symbol.
func (pkg *Package) findFuncs(symbol string) (funcs []*doc.Func) {
for _, fun := range pkg.doc.Funcs {
if match(symbol, fun.Name) {
funcs = append(funcs, fun)
}
}
return
}
// findTypes finds the doc.Types that describes the symbol.
// If symbol is empty, it finds all exported types.
func (pkg *Package) findTypes(symbol string) (types []*doc.Type) {
for _, typ := range pkg.doc.Types {
if symbol == "" && isExported(typ.Name) || match(symbol, typ.Name) {
types = append(types, typ)
}
}
return
}
// findTypeSpec returns the ast.TypeSpec within the declaration that defines the symbol.
// The name must match exactly.
func (pkg *Package) findTypeSpec(decl *ast.GenDecl, symbol string) *ast.TypeSpec {
for _, spec := range decl.Specs {
typeSpec := spec.(*ast.TypeSpec) // Must succeed.
if symbol == typeSpec.Name.Name {
return typeSpec
}
}
return nil
}
// symbolDoc prints the docs for symbol. There may be multiple matches.
// If symbol matches a type, output includes its methods factories and associated constants.
// If there is no top-level symbol, symbolDoc looks for methods that match.
func (pkg *Package) symbolDoc(symbol string) bool {
defer pkg.flush()
found := false
// Functions.
for _, fun := range pkg.findFuncs(symbol) {
if !found {
pkg.packageClause(true)
}
// Symbol is a function.
decl := fun.Decl
decl.Body = nil
pkg.emit(fun.Doc, decl)
found = true
}
// Constants and variables behave the same.
values := pkg.findValues(symbol, pkg.doc.Consts)
values = append(values, pkg.findValues(symbol, pkg.doc.Vars)...)
for _, value := range values {
// Print each spec only if there is at least one exported symbol in it.
// (See issue 11008.)
// TODO: Should we elide unexported symbols from a single spec?
// It's an unlikely scenario, probably not worth the trouble.
// TODO: Would be nice if go/doc did this for us.
specs := make([]ast.Spec, 0, len(value.Decl.Specs))
for _, spec := range value.Decl.Specs {
vspec := spec.(*ast.ValueSpec)
for _, ident := range vspec.Names {
if isExported(ident.Name) {
specs = append(specs, vspec)
break
}
}
}
if len(specs) == 0 {
continue
}
value.Decl.Specs = specs
if !found {
pkg.packageClause(true)
}
pkg.emit(value.Doc, value.Decl)
found = true
}
// Types.
for _, typ := range pkg.findTypes(symbol) {
if !found {
pkg.packageClause(true)
}
decl := typ.Decl
spec := pkg.findTypeSpec(decl, typ.Name)
trimUnexportedElems(spec)
// If there are multiple types defined, reduce to just this one.
if len(decl.Specs) > 1 {
decl.Specs = []ast.Spec{spec}
}
pkg.emit(typ.Doc, decl)
// Show associated methods, constants, etc.
if len(typ.Consts) > 0 || len(typ.Vars) > 0 || len(typ.Funcs) > 0 || len(typ.Methods) > 0 {
pkg.Printf("\n")
}
pkg.valueSummary(typ.Consts)
pkg.valueSummary(typ.Vars)
pkg.funcSummary(typ.Funcs, true)
pkg.funcSummary(typ.Methods, true)
found = true
}
if !found {
// See if there are methods.
if !pkg.printMethodDoc("", symbol) {
return false
}
}
return true
}
// trimUnexportedElems modifies spec in place to elide unexported fields from
// structs and methods from interfaces (unless the unexported flag is set).
func trimUnexportedElems(spec *ast.TypeSpec) {
if unexported {
return
}
switch typ := spec.Type.(type) {
case *ast.StructType:
typ.Fields = trimUnexportedFields(typ.Fields, false)
case *ast.InterfaceType:
typ.Methods = trimUnexportedFields(typ.Methods, true)
}
}
// trimUnexportedFields returns the field list trimmed of unexported fields.
func trimUnexportedFields(fields *ast.FieldList, isInterface bool) *ast.FieldList {
what := "methods"
if !isInterface {
what = "fields"
}
trimmed := false
list := make([]*ast.Field, 0, len(fields.List))
for _, field := range fields.List {
names := field.Names
if len(names) == 0 {
// Embedded type. Use the name of the type. It must be of type ident or *ident.
// Nothing else is allowed.
switch ident := field.Type.(type) {
case *ast.Ident:
if isInterface && ident.Name == "error" && ident.Obj == nil {
// For documentation purposes, we consider the builtin error
// type special when embedded in an interface, such that it
// always gets shown publicly.
list = append(list, field)
continue
}
names = []*ast.Ident{ident}
case *ast.StarExpr:
// Must have the form *identifier.
// This is only valid on embedded types in structs.
if ident, ok := ident.X.(*ast.Ident); ok && !isInterface {
names = []*ast.Ident{ident}
}
case *ast.SelectorExpr:
// An embedded type may refer to a type in another package.
names = []*ast.Ident{ident.Sel}
}
if names == nil {
// Can only happen if AST is incorrect. Safe to continue with a nil list.
log.Print("invalid program: unexpected type for embedded field")
}
}
// Trims if any is unexported. Good enough in practice.
ok := true
for _, name := range names {
if !isExported(name.Name) {
trimmed = true
ok = false
break
}
}
if ok {
list = append(list, field)
}
}
if !trimmed {
return fields
}
unexportedField := &ast.Field{
Type: &ast.Ident{
// Hack: printer will treat this as a field with a named type.
// Setting Name and NamePos to ("", fields.Closing-1) ensures that
// when Pos and End are called on this field, they return the
// position right before closing '}' character.
Name: "",
NamePos: fields.Closing - 1,
},
Comment: &ast.CommentGroup{
List: []*ast.Comment{{Text: fmt.Sprintf("// Has unexported %s.\n", what)}},
},
}
return &ast.FieldList{
Opening: fields.Opening,
List: append(list, unexportedField),
Closing: fields.Closing,
}
}
// printMethodDoc prints the docs for matches of symbol.method.
// If symbol is empty, it prints all methods that match the name.
// It reports whether it found any methods.
func (pkg *Package) printMethodDoc(symbol, method string) bool {
defer pkg.flush()
types := pkg.findTypes(symbol)
if types == nil {
if symbol == "" {
return false
}
pkg.Fatalf("symbol %s is not a type in package %s installed in %q", symbol, pkg.name, pkg.build.ImportPath)
}
found := false
for _, typ := range types {
for _, meth := range typ.Methods {
if match(method, meth.Name) {
decl := meth.Decl
decl.Body = nil
pkg.emit(meth.Doc, decl)
found = true
}
}
}
return found
}
// methodDoc prints the docs for matches of symbol.method.
func (pkg *Package) methodDoc(symbol, method string) bool {
defer pkg.flush()
return pkg.printMethodDoc(symbol, method)
}
// match reports whether the user's symbol matches the program's.
// A lower-case character in the user's string matches either case in the program's.
// The program string must be exported.
func match(user, program string) bool {
if !isExported(program) {
return false
}
if matchCase {
return user == program
}
for _, u := range user {
p, w := utf8.DecodeRuneInString(program)
program = program[w:]
if u == p {
continue
}
if unicode.IsLower(u) && simpleFold(u) == simpleFold(p) {
continue
}
return false
}
return program == ""
}
// simpleFold returns the minimum rune equivalent to r
// under Unicode-defined simple case folding.
func simpleFold(r rune) rune {
for {
r1 := unicode.SimpleFold(r)
if r1 <= r {
return r1 // wrapped around, found min
}
r = r1
}
}