// 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 ( "go/ast" "go/token" ) // 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 } // 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 } // 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 } // 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. type Mode int const ( // extract documentation for all package-level declarations, // not just exported ones AllDecls Mode = 1 << iota // show all embedded methods, not just the ones of // invisible (unexported) anonymous fields AllMethods ) // New computes the package documentation for the given package AST. // New takes ownership of the AST pkg and may edit or overwrite it. // 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), } }