...
Run Format

Source file src/cmd/doc/pkg.go

Documentation: cmd/doc

  // 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)
  		}
  	}
  }
  
  // oneLineNode returns a one-line summary of the given input node.
  func (pkg *Package) oneLineNode(node ast.Node) string {
  	const maxDepth = 10
  	return pkg.oneLineNodeDepth(node, maxDepth)
  }
  
  // oneLineNodeDepth returns a one-line summary of the given input node.
  // The depth specifies the maximum depth when traversing the AST.
  func (pkg *Package) oneLineNodeDepth(node ast.Node, depth int) string {
  	const dotDotDot = "..."
  	if depth == 0 {
  		return dotDotDot
  	}
  	depth--
  
  	switch n := node.(type) {
  	case nil:
  		return ""
  
  	case *ast.GenDecl:
  		// Formats const and var declarations.
  		trailer := ""
  		if len(n.Specs) > 1 {
  			trailer = " " + dotDotDot
  		}
  
  		// Find the first relevant spec.
  		typ := ""
  		for i, spec := range n.Specs {
  			valueSpec := spec.(*ast.ValueSpec) // Must succeed; we can't mix types in one GenDecl.
  
  			// The type name may carry over from a previous specification in the
  			// case of constants and iota.
  			if valueSpec.Type != nil {
  				typ = fmt.Sprintf(" %s", pkg.oneLineNodeDepth(valueSpec.Type, depth))
  			} else if len(valueSpec.Values) > 0 {
  				typ = ""
  			}
  
  			if !isExported(valueSpec.Names[0].Name) {
  				continue
  			}
  			val := ""
  			if i < len(valueSpec.Values) && valueSpec.Values[i] != nil {
  				val = fmt.Sprintf(" = %s", pkg.oneLineNodeDepth(valueSpec.Values[i], depth))
  			}
  			return fmt.Sprintf("%s %s%s%s%s", n.Tok, valueSpec.Names[0], typ, val, trailer)
  		}
  		return ""
  
  	case *ast.FuncDecl:
  		// Formats func declarations.
  		name := n.Name.Name
  		recv := pkg.oneLineNodeDepth(n.Recv, depth)
  		if len(recv) > 0 {
  			recv = "(" + recv + ") "
  		}
  		fnc := pkg.oneLineNodeDepth(n.Type, depth)
  		if strings.Index(fnc, "func") == 0 {
  			fnc = fnc[4:]
  		}
  		return fmt.Sprintf("func %s%s%s", recv, name, fnc)
  
  	case *ast.TypeSpec:
  		sep := " "
  		if n.Assign.IsValid() {
  			sep = " = "
  		}
  		return fmt.Sprintf("type %s%s%s", n.Name.Name, sep, pkg.oneLineNodeDepth(n.Type, depth))
  
  	case *ast.FuncType:
  		var params []string
  		if n.Params != nil {
  			for _, field := range n.Params.List {
  				params = append(params, pkg.oneLineField(field, depth))
  			}
  		}
  		needParens := false
  		var results []string
  		if n.Results != nil {
  			needParens = needParens || len(n.Results.List) > 1
  			for _, field := range n.Results.List {
  				needParens = needParens || len(field.Names) > 0
  				results = append(results, pkg.oneLineField(field, depth))
  			}
  		}
  
  		param := joinStrings(params)
  		if len(results) == 0 {
  			return fmt.Sprintf("func(%s)", param)
  		}
  		result := joinStrings(results)
  		if !needParens {
  			return fmt.Sprintf("func(%s) %s", param, result)
  		}
  		return fmt.Sprintf("func(%s) (%s)", param, result)
  
  	case *ast.StructType:
  		if n.Fields == nil || len(n.Fields.List) == 0 {
  			return "struct{}"
  		}
  		return "struct{ ... }"
  
  	case *ast.InterfaceType:
  		if n.Methods == nil || len(n.Methods.List) == 0 {
  			return "interface{}"
  		}
  		return "interface{ ... }"
  
  	case *ast.FieldList:
  		if n == nil || len(n.List) == 0 {
  			return ""
  		}
  		if len(n.List) == 1 {
  			return pkg.oneLineField(n.List[0], depth)
  		}
  		return dotDotDot
  
  	case *ast.FuncLit:
  		return pkg.oneLineNodeDepth(n.Type, depth) + " { ... }"
  
  	case *ast.CompositeLit:
  		typ := pkg.oneLineNodeDepth(n.Type, depth)
  		if len(n.Elts) == 0 {
  			return fmt.Sprintf("%s{}", typ)
  		}
  		return fmt.Sprintf("%s{ %s }", typ, dotDotDot)
  
  	case *ast.ArrayType:
  		length := pkg.oneLineNodeDepth(n.Len, depth)
  		element := pkg.oneLineNodeDepth(n.Elt, depth)
  		return fmt.Sprintf("[%s]%s", length, element)
  
  	case *ast.MapType:
  		key := pkg.oneLineNodeDepth(n.Key, depth)
  		value := pkg.oneLineNodeDepth(n.Value, depth)
  		return fmt.Sprintf("map[%s]%s", key, value)
  
  	case *ast.CallExpr:
  		fnc := pkg.oneLineNodeDepth(n.Fun, depth)
  		var args []string
  		for _, arg := range n.Args {
  			args = append(args, pkg.oneLineNodeDepth(arg, depth))
  		}
  		return fmt.Sprintf("%s(%s)", fnc, joinStrings(args))
  
  	case *ast.UnaryExpr:
  		return fmt.Sprintf("%s%s", n.Op, pkg.oneLineNodeDepth(n.X, depth))
  
  	case *ast.Ident:
  		return n.Name
  
  	default:
  		// As a fallback, use default formatter for all unknown node types.
  		buf := new(bytes.Buffer)
  		format.Node(buf, pkg.fs, node)
  		s := buf.String()
  		if strings.Contains(s, "\n") {
  			return dotDotDot
  		}
  		return s
  	}
  }
  
  // oneLineField returns a one-line summary of the field.
  func (pkg *Package) oneLineField(field *ast.Field, depth int) string {
  	var names []string
  	for _, name := range field.Names {
  		names = append(names, name.Name)
  	}
  	if len(names) == 0 {
  		return pkg.oneLineNodeDepth(field.Type, depth)
  	}
  	return joinStrings(names) + " " + pkg.oneLineNodeDepth(field.Type, depth)
  }
  
  // joinStrings formats the input as a comma-separated list,
  // but truncates the list at some reasonable length if necessary.
  func joinStrings(ss []string) string {
  	var n int
  	for i, s := range ss {
  		n += len(s) + len(", ")
  		if n > punchedCardWidth {
  			ss = append(ss[:i:i], "...")
  			break
  		}
  	}
  	return strings.Join(ss, ", ")
  }
  
  // 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, false)
  	pkg.valueSummary(pkg.doc.Vars, false)
  	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.
  // If all the types in a constant or variable declaration belong to the same
  // type they can be printed by typeSummary, and so can be suppressed here.
  func (pkg *Package) valueSummary(values []*doc.Value, showGrouped bool) {
  	var isGrouped map[*doc.Value]bool
  	if !showGrouped {
  		isGrouped = make(map[*doc.Value]bool)
  		for _, typ := range pkg.doc.Types {
  			if !isExported(typ.Name) {
  				continue
  			}
  			for _, c := range typ.Consts {
  				isGrouped[c] = true
  			}
  			for _, v := range typ.Vars {
  				isGrouped[v] = true
  			}
  		}
  	}
  
  	for _, value := range values {
  		if !isGrouped[value] {
  			if decl := pkg.oneLineNode(value.Decl); decl != "" {
  				pkg.Printf("%s\n", 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 {
  			if isExported(typ.Name) {
  				for _, f := range typ.Funcs {
  					isConstructor[f] = true
  				}
  			}
  		}
  	}
  	for _, fun := range funcs {
  		// Exported functions only. The go/doc package does not include methods here.
  		if isExported(fun.Name) {
  			if !isConstructor[fun] {
  				pkg.Printf("%s\n", pkg.oneLineNode(fun.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.Printf("%s\n", pkg.oneLineNode(typeSpec))
  				// Now print the consts, vars, and constructors.
  				for _, c := range typ.Consts {
  					if decl := pkg.oneLineNode(c.Decl); decl != "" {
  						pkg.Printf(indent+"%s\n", decl)
  					}
  				}
  				for _, v := range typ.Vars {
  					if decl := pkg.oneLineNode(v.Decl); decl != "" {
  						pkg.Printf(indent+"%s\n", decl)
  					}
  				}
  				for _, constructor := range typ.Funcs {
  					if isExported(constructor.Name) {
  						pkg.Printf(indent+"%s\n", pkg.oneLineNode(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))
  		var typ ast.Expr
  		for _, spec := range value.Decl.Specs {
  			vspec := spec.(*ast.ValueSpec)
  
  			// The type name may carry over from a previous specification in the
  			// case of constants and iota.
  			if vspec.Type != nil {
  				typ = vspec.Type
  			}
  
  			for _, ident := range vspec.Names {
  				if isExported(ident.Name) {
  					if vspec.Type == nil && vspec.Values == nil && typ != nil {
  						// This a standalone identifier, as in the case of iota usage.
  						// Thus, assume the type comes from the previous type.
  						vspec.Type = &ast.Ident{
  							Name:    string(pkg.oneLineNode(typ)),
  							NamePos: vspec.End() - 1,
  						}
  					}
  
  					specs = append(specs, vspec)
  					typ = nil // Only inject type on first exported identifier
  					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, true)
  		pkg.valueSummary(typ.Vars, true)
  		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 {
  		if len(typ.Methods) > 0 {
  			for _, meth := range typ.Methods {
  				if match(method, meth.Name) {
  					decl := meth.Decl
  					decl.Body = nil
  					pkg.emit(meth.Doc, decl)
  					found = true
  				}
  			}
  			continue
  		}
  		// Type may be an interface. The go/doc package does not attach
  		// an interface's methods to the doc.Type. We need to dig around.
  		spec := pkg.findTypeSpec(typ.Decl, typ.Name)
  		inter, ok := spec.Type.(*ast.InterfaceType)
  		if !ok {
  			// Not an interface type.
  			continue
  		}
  		for _, iMethod := range inter.Methods.List {
  			// This is an interface, so there can be only one name.
  			// TODO: Anonymous methods (embedding)
  			if len(iMethod.Names) == 0 {
  				continue
  			}
  			name := iMethod.Names[0].Name
  			if match(method, name) {
  				if iMethod.Doc != nil {
  					for _, comment := range iMethod.Doc.List {
  						doc.ToText(&pkg.buf, comment.Text, "", indent, indentedWidth)
  					}
  				}
  				s := pkg.oneLineNode(iMethod.Type)
  				// Hack: s starts "func" but there is no name present.
  				// We could instead build a FuncDecl but it's not worthwhile.
  				lineComment := ""
  				if iMethod.Comment != nil {
  					lineComment = fmt.Sprintf("  %s", iMethod.Comment.List[0].Text)
  				}
  				pkg.Printf("func %s%s%s\n", name, s[4:], lineComment)
  				found = true
  			}
  		}
  	}
  	return found
  }
  
  // printFieldDoc prints the docs for matches of symbol.fieldName.
  // It reports whether it found any field.
  // Both symbol and fieldName must be non-empty or it returns false.
  func (pkg *Package) printFieldDoc(symbol, fieldName string) bool {
  	if symbol == "" || fieldName == "" {
  		return false
  	}
  	defer pkg.flush()
  	types := pkg.findTypes(symbol)
  	if types == nil {
  		pkg.Fatalf("symbol %s is not a type in package %s installed in %q", symbol, pkg.name, pkg.build.ImportPath)
  	}
  	found := false
  	numUnmatched := 0
  	for _, typ := range types {
  		// Type must be a struct.
  		spec := pkg.findTypeSpec(typ.Decl, typ.Name)
  		structType, ok := spec.Type.(*ast.StructType)
  		if !ok {
  			// Not a struct type.
  			continue
  		}
  		for _, field := range structType.Fields.List {
  			// TODO: Anonymous fields.
  			for _, name := range field.Names {
  				if !match(fieldName, name.Name) {
  					numUnmatched++
  					continue
  				}
  				if !found {
  					pkg.Printf("type %s struct {\n", typ.Name)
  				}
  				if field.Doc != nil {
  					for _, comment := range field.Doc.List {
  						doc.ToText(&pkg.buf, comment.Text, indent, indent, indentedWidth)
  					}
  				}
  				s := pkg.oneLineNode(field.Type)
  				lineComment := ""
  				if field.Comment != nil {
  					lineComment = fmt.Sprintf("  %s", field.Comment.List[0].Text)
  				}
  				pkg.Printf("%s%s %s%s\n", indent, name, s, lineComment)
  				found = true
  			}
  		}
  	}
  	if found {
  		if numUnmatched > 0 {
  			pkg.Printf("\n    // ... other fields elided ...\n")
  		}
  		pkg.Printf("}\n")
  	}
  	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)
  }
  
  // fieldDoc prints the docs for matches of symbol.field.
  func (pkg *Package) fieldDoc(symbol, field string) bool {
  	defer pkg.flush()
  	return pkg.printFieldDoc(symbol, field)
  }
  
  // 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
  	}
  }
  

View as plain text