1 // Copyright 2009 The Go Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 // Package doc extracts source code documentation from a Go AST. 6 package doc 7 8 import ( 9 "go/ast" 10 "go/token" 11 ) 12 13 // Package is the documentation for an entire package. 14 type Package struct { 15 Doc string 16 Name string 17 ImportPath string 18 Imports []string 19 Filenames []string 20 Notes map[string][]*Note 21 22 // Deprecated: For backward compatibility Bugs is still populated, 23 // but all new code should use Notes instead. 24 Bugs []string 25 26 // declarations 27 Consts []*Value 28 Types []*Type 29 Vars []*Value 30 Funcs []*Func 31 } 32 33 // Value is the documentation for a (possibly grouped) var or const declaration. 34 type Value struct { 35 Doc string 36 Names []string // var or const names in declaration order 37 Decl *ast.GenDecl 38 39 order int 40 } 41 42 // Type is the documentation for a type declaration. 43 type Type struct { 44 Doc string 45 Name string 46 Decl *ast.GenDecl 47 48 // associated declarations 49 Consts []*Value // sorted list of constants of (mostly) this type 50 Vars []*Value // sorted list of variables of (mostly) this type 51 Funcs []*Func // sorted list of functions returning this type 52 Methods []*Func // sorted list of methods (including embedded ones) of this type 53 } 54 55 // Func is the documentation for a func declaration. 56 type Func struct { 57 Doc string 58 Name string 59 Decl *ast.FuncDecl 60 61 // methods 62 // (for functions, these fields have the respective zero value) 63 Recv string // actual receiver "T" or "*T" 64 Orig string // original receiver "T" or "*T" 65 Level int // embedding level; 0 means not embedded 66 } 67 68 // A Note represents a marked comment starting with "MARKER(uid): note body". 69 // Any note with a marker of 2 or more upper case [A-Z] letters and a uid of 70 // at least one character is recognized. The ":" following the uid is optional. 71 // Notes are collected in the Package.Notes map indexed by the notes marker. 72 type Note struct { 73 Pos, End token.Pos // position range of the comment containing the marker 74 UID string // uid found with the marker 75 Body string // note body text 76 } 77 78 // Mode values control the operation of New. 79 type Mode int 80 81 const ( 82 // AllDecls says to extract documentation for all package-level 83 // declarations, not just exported ones. 84 AllDecls Mode = 1 << iota 85 86 // AllMethods says to show all embedded methods, not just the ones of 87 // invisible (unexported) anonymous fields. 88 AllMethods 89 90 // PreserveAST says to leave the AST unmodified. Originally, pieces of 91 // the AST such as function bodies were nil-ed out to save memory in 92 // godoc, but not all programs want that behavior. 93 PreserveAST 94 ) 95 96 // New computes the package documentation for the given package AST. 97 // New takes ownership of the AST pkg and may edit or overwrite it. 98 // 99 func New(pkg *ast.Package, importPath string, mode Mode) *Package { 100 var r reader 101 r.readPackage(pkg, mode) 102 r.computeMethodSets() 103 r.cleanupTypes() 104 return &Package{ 105 Doc: r.doc, 106 Name: pkg.Name, 107 ImportPath: importPath, 108 Imports: sortedKeys(r.imports), 109 Filenames: r.filenames, 110 Notes: r.notes, 111 Bugs: noteBodies(r.notes["BUG"]), 112 Consts: sortedValues(r.values, token.CONST), 113 Types: sortedTypes(r.types, mode&AllMethods != 0), 114 Vars: sortedValues(r.values, token.VAR), 115 Funcs: sortedFuncs(r.funcs, true), 116 } 117 } 118