Source: doc.go in package go/doc

Package doc extracts source code documentation from a Go AST.

package doc

import (
	"fmt"
	"go/ast"
	"go/token"
	"strings"
)

Package is the documentation for an entire package.

type Package struct {
	Doc        string
	Name       string
	ImportPath string
	Imports    []string
	Filenames  []string
	Notes      map[string][]*Note

Deprecated: For backward compatibility Bugs is still populated, but all new code should use Notes instead.

	Bugs []string

declarations

	Consts []*Value
	Types  []*Type
	Vars   []*Value
	Funcs  []*Func

Examples is a sorted list of examples associated with the package. Examples are extracted from _test.go files provided to NewFromFiles.

	Examples []*Example
}

Value is the documentation for a (possibly grouped) var or const declaration.

type Value struct {
	Doc   string
	Names []string // var or const names in declaration order
	Decl  *ast.GenDecl

	order int
}

Type is the documentation for a type declaration.

type Type struct {
	Doc  string
	Name string
	Decl *ast.GenDecl

associated declarations

	Consts  []*Value // sorted list of constants of (mostly) this type
	Vars    []*Value // sorted list of variables of (mostly) this type
	Funcs   []*Func  // sorted list of functions returning this type
	Methods []*Func  // sorted list of methods (including embedded ones) of this type

Examples is a sorted list of examples associated with this type. Examples are extracted from _test.go files provided to NewFromFiles.

	Examples []*Example
}

Func is the documentation for a func declaration.

type Func struct {
	Doc  string
	Name string
	Decl *ast.FuncDecl

methods (for functions, these fields have the respective zero value)

	Recv  string // actual   receiver "T" or "*T"
	Orig  string // original receiver "T" or "*T"
	Level int    // embedding level; 0 means not embedded

Examples is a sorted list of examples associated with this function or method. Examples are extracted from _test.go files provided to NewFromFiles.

	Examples []*Example
}

A Note represents a marked comment starting with "MARKER(uid): note body". Any note with a marker of 2 or more upper case [A-Z] letters and a uid of at least one character is recognized. The ":" following the uid is optional. Notes are collected in the Package.Notes map indexed by the notes marker.

type Note struct {
	Pos, End token.Pos // position range of the comment containing the marker
	UID      string    // uid found with the marker
	Body     string    // note body text
}

Mode values control the operation of New and NewFromFiles.

type Mode int

AllDecls says to extract documentation for all package-level declarations, not just exported ones.

	AllDecls Mode = 1 << iota

AllMethods says to show all embedded methods, not just the ones of invisible (unexported) anonymous fields.

	AllMethods

PreserveAST says to leave the AST unmodified. Originally, pieces of the AST such as function bodies were nil-ed out to save memory in godoc, but not all programs want that behavior.

	PreserveAST
)

New computes the package documentation for the given package AST. New takes ownership of the AST pkg and may edit or overwrite it. To have the Examples fields populated, use NewFromFiles and include the package's _test.go files.

func New(pkg *ast.Package, importPath string, mode Mode) *Package {
	var r reader
	r.readPackage(pkg, mode)
	r.computeMethodSets()
	r.cleanupTypes()
	return &Package{
		Doc:        r.doc,
		Name:       pkg.Name,
		ImportPath: importPath,
		Imports:    sortedKeys(r.imports),
		Filenames:  r.filenames,
		Notes:      r.notes,
		Bugs:       noteBodies(r.notes["BUG"]),
		Consts:     sortedValues(r.values, token.CONST),
		Types:      sortedTypes(r.types, mode&AllMethods != 0),
		Vars:       sortedValues(r.values, token.VAR),
		Funcs:      sortedFuncs(r.funcs, true),
	}
}

NewFromFiles computes documentation for a package. The package is specified by a list of *ast.Files and corresponding file set, which must not be nil. NewFromFiles uses all provided files when computing documentation, so it is the caller's responsibility to provide only the files that match the desired build context. "go/build".Context.MatchFile can be used for determining whether a file matches a build context with the desired GOOS and GOARCH values, and other build constraints. The import path of the package is specified by importPath. Examples found in _test.go files are associated with the corresponding type, function, method, or the package, based on their name. If the example has a suffix in its name, it is set in the Example.Suffix field. Examples with malformed names are skipped. Optionally, a single extra argument of type Mode can be provided to control low-level aspects of the documentation extraction behavior. NewFromFiles takes ownership of the AST files and may edit them, unless the PreserveAST Mode bit is on.

Check for invalid API usage.

	if fset == nil {
		panic(fmt.Errorf("doc.NewFromFiles: no token.FileSet provided (fset == nil)"))
	}
	var mode Mode
	switch len(opts) { // There can only be 0 or 1 options, so a simple switch works for now.

Nothing to do.

	case 1:
		m, ok := opts[0].(Mode)
		if !ok {
			panic(fmt.Errorf("doc.NewFromFiles: option argument type must be doc.Mode"))
		}
		mode = m
	default:
		panic(fmt.Errorf("doc.NewFromFiles: there must not be more than 1 option argument"))
	}

Collect .go and _test.go files.

	var (
		goFiles     = make(map[string]*ast.File)
		testGoFiles []*ast.File
	)
	for i := range files {
		f := fset.File(files[i].Pos())
		if f == nil {
			return nil, fmt.Errorf("file files[%d] is not found in the provided file set", i)
		}
		switch name := f.Name(); {
		case strings.HasSuffix(name, ".go") && !strings.HasSuffix(name, "_test.go"):
			goFiles[name] = files[i]
		case strings.HasSuffix(name, "_test.go"):
			testGoFiles = append(testGoFiles, files[i])
		default:
			return nil, fmt.Errorf("file files[%d] filename %q does not have a .go extension", i, name)
		}
	}

TODO(dmitshur,gri): A relatively high level call to ast.NewPackage with a simpleImporter ast.Importer implementation is made below. It might be possible to short-circuit and simplify.

Compute package documentation.

	pkg, _ := ast.NewPackage(fset, goFiles, simpleImporter, nil) // Ignore errors that can happen due to unresolved identifiers.
	p := New(pkg, importPath, mode)
	classifyExamples(p, Examples(testGoFiles...))
	return p, nil
}

simpleImporter returns a (dummy) package object named by the last path component of the provided package path (as is the convention for packages). This is sufficient to resolve package identifiers without doing an actual import. It never returns an error.

func simpleImporter(imports map[string]*ast.Object, path string) (*ast.Object, error) {
	pkg := imports[path]

note that strings.LastIndex returns -1 if there is no "/"

		pkg = ast.NewObj(ast.Pkg, path[strings.LastIndex(path, "/")+1:])
		pkg.Data = ast.NewScope(nil) // required by ast.NewPackage for dot-import
		imports[path] = pkg
	}
	return pkg, nil