Source file src/pkg/go/doc/doc.go
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 Bugs []string 21 22 // declarations 23 Consts []*Value 24 Types []*Type 25 Vars []*Value 26 Funcs []*Func 27 } 28 29 // Value is the documentation for a (possibly grouped) var or const declaration. 30 type Value struct { 31 Doc string 32 Names []string // var or const names in declaration order 33 Decl *ast.GenDecl 34 35 order int 36 } 37 38 // Type is the documentation for a type declaration. 39 type Type struct { 40 Doc string 41 Name string 42 Decl *ast.GenDecl 43 44 // associated declarations 45 Consts []*Value // sorted list of constants of (mostly) this type 46 Vars []*Value // sorted list of variables of (mostly) this type 47 Funcs []*Func // sorted list of functions returning this type 48 Methods []*Func // sorted list of methods (including embedded ones) of this type 49 } 50 51 // Func is the documentation for a func declaration. 52 type Func struct { 53 Doc string 54 Name string 55 Decl *ast.FuncDecl 56 57 // methods 58 // (for functions, these fields have the respective zero value) 59 Recv string // actual receiver "T" or "*T" 60 Orig string // original receiver "T" or "*T" 61 Level int // embedding level; 0 means not embedded 62 } 63 64 // Mode values control the operation of New. 65 type Mode int 66 67 const ( 68 // extract documentation for all package-level declarations, 69 // not just exported ones 70 AllDecls Mode = 1 << iota 71 72 // show all embedded methods, not just the ones of 73 // invisible (unexported) anonymous fields 74 AllMethods 75 ) 76 77 // New computes the package documentation for the given package AST. 78 // New takes ownership of the AST pkg and may edit or overwrite it. 79 // 80 func New(pkg *ast.Package, importPath string, mode Mode) *Package { 81 var r reader 82 r.readPackage(pkg, mode) 83 r.computeMethodSets() 84 r.cleanupTypes() 85 return &Package{ 86 Doc: r.doc, 87 Name: pkg.Name, 88 ImportPath: importPath, 89 Imports: sortedKeys(r.imports), 90 Filenames: r.filenames, 91 Bugs: r.bugs, 92 Consts: sortedValues(r.values, token.CONST), 93 Types: sortedTypes(r.types, mode&AllMethods != 0), 94 Vars: sortedValues(r.values, token.VAR), 95 Funcs: sortedFuncs(r.funcs, true), 96 } 97 }