github.com/gocuntian/go@v0.0.0-20160610041250-fee02d270bf8/src/go/doc/doc.go (about)

     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  	// extract documentation for all package-level declarations,
    83  	// not just exported ones
    84  	AllDecls Mode = 1 << iota
    85  
    86  	// show all embedded methods, not just the ones of
    87  	// invisible (unexported) anonymous fields
    88  	AllMethods
    89  )
    90  
    91  // New computes the package documentation for the given package AST.
    92  // New takes ownership of the AST pkg and may edit or overwrite it.
    93  //
    94  func New(pkg *ast.Package, importPath string, mode Mode) *Package {
    95  	var r reader
    96  	r.readPackage(pkg, mode)
    97  	r.computeMethodSets()
    98  	r.cleanupTypes()
    99  	return &Package{
   100  		Doc:        r.doc,
   101  		Name:       pkg.Name,
   102  		ImportPath: importPath,
   103  		Imports:    sortedKeys(r.imports),
   104  		Filenames:  r.filenames,
   105  		Notes:      r.notes,
   106  		Bugs:       noteBodies(r.notes["BUG"]),
   107  		Consts:     sortedValues(r.values, token.CONST),
   108  		Types:      sortedTypes(r.types, mode&AllMethods != 0),
   109  		Vars:       sortedValues(r.values, token.VAR),
   110  		Funcs:      sortedFuncs(r.funcs, true),
   111  	}
   112  }