// Copyright 2009 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 doc extracts source code documentation from a Go AST.
package doc import ( ) // 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 const ( // 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 ( *ast.Package, string, Mode) *Package { var reader .readPackage(, ) .computeMethodSets() .cleanupTypes() return &Package{ Doc: .doc, Name: .Name, ImportPath: , Imports: sortedKeys(.imports), Filenames: .filenames, Notes: .notes, Bugs: noteBodies(.notes["BUG"]), Consts: sortedValues(.values, token.CONST), Types: sortedTypes(.types, &AllMethods != 0), Vars: sortedValues(.values, token.VAR), Funcs: sortedFuncs(.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. // func ( *token.FileSet, []*ast.File, string, ...interface{}) (*Package, error) { // Check for invalid API usage. if == nil { panic(fmt.Errorf("doc.NewFromFiles: no token.FileSet provided (fset == nil)")) } var Mode switch len() { // There can only be 0 or 1 options, so a simple switch works for now. case 0: // Nothing to do. case 1: , := [0].(Mode) if ! { panic(fmt.Errorf("doc.NewFromFiles: option argument type must be doc.Mode")) } = default: panic(fmt.Errorf("doc.NewFromFiles: there must not be more than 1 option argument")) } // Collect .go and _test.go files. var ( = make(map[string]*ast.File) []*ast.File ) for := range { := .File([].Pos()) if == nil { return nil, fmt.Errorf("file files[%d] is not found in the provided file set", ) } switch := .Name(); { case strings.HasSuffix(, ".go") && !strings.HasSuffix(, "_test.go"): [] = [] case strings.HasSuffix(, "_test.go"): = append(, []) default: return nil, fmt.Errorf("file files[%d] filename %q does not have a .go extension", , ) } } // 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. , := ast.NewPackage(, , simpleImporter, nil) // Ignore errors that can happen due to unresolved identifiers. := New(, , ) classifyExamples(, Examples(...)) return , 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( map[string]*ast.Object, string) (*ast.Object, error) { := [] if == nil { // note that strings.LastIndex returns -1 if there is no "/" = ast.NewObj(ast.Pkg, [strings.LastIndex(, "/")+1:]) .Data = ast.NewScope(nil) // required by ast.NewPackage for dot-import [] = } return , nil }