github.com/varialus/godfly@v0.0.0-20130904042352-1934f9f095ab/src/pkg/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  	// DEPRECATED. For backward compatibility Bugs is still populated,
    22  	// but all new code should use Notes instead.
    23  	Bugs []string
    24  
    25  	// declarations
    26  	Consts []*Value
    27  	Types  []*Type
    28  	Vars   []*Value
    29  	Funcs  []*Func
    30  }
    31  
    32  // Value is the documentation for a (possibly grouped) var or const declaration.
    33  type Value struct {
    34  	Doc   string
    35  	Names []string // var or const names in declaration order
    36  	Decl  *ast.GenDecl
    37  
    38  	order int
    39  }
    40  
    41  // Type is the documentation for a type declaration.
    42  type Type struct {
    43  	Doc  string
    44  	Name string
    45  	Decl *ast.GenDecl
    46  
    47  	// associated declarations
    48  	Consts  []*Value // sorted list of constants of (mostly) this type
    49  	Vars    []*Value // sorted list of variables of (mostly) this type
    50  	Funcs   []*Func  // sorted list of functions returning this type
    51  	Methods []*Func  // sorted list of methods (including embedded ones) of this type
    52  }
    53  
    54  // Func is the documentation for a func declaration.
    55  type Func struct {
    56  	Doc  string
    57  	Name string
    58  	Decl *ast.FuncDecl
    59  
    60  	// methods
    61  	// (for functions, these fields have the respective zero value)
    62  	Recv  string // actual   receiver "T" or "*T"
    63  	Orig  string // original receiver "T" or "*T"
    64  	Level int    // embedding level; 0 means not embedded
    65  }
    66  
    67  // A Note represents a marked comment starting with "MARKER(uid): note body".
    68  // Any note with a marker of 2 or more upper case [A-Z] letters and a uid of
    69  // at least one character is recognized. The ":" following the uid is optional.
    70  // Notes are collected in the Package.Notes map indexed by the notes marker.
    71  type Note struct {
    72  	Pos, End token.Pos // position range of the comment containing the marker
    73  	UID      string    // uid found with the marker
    74  	Body     string    // note body text
    75  }
    76  
    77  // Mode values control the operation of New.
    78  type Mode int
    79  
    80  const (
    81  	// extract documentation for all package-level declarations,
    82  	// not just exported ones
    83  	AllDecls Mode = 1 << iota
    84  
    85  	// show all embedded methods, not just the ones of
    86  	// invisible (unexported) anonymous fields
    87  	AllMethods
    88  )
    89  
    90  // New computes the package documentation for the given package AST.
    91  // New takes ownership of the AST pkg and may edit or overwrite it.
    92  //
    93  func New(pkg *ast.Package, importPath string, mode Mode) *Package {
    94  	var r reader
    95  	r.readPackage(pkg, mode)
    96  	r.computeMethodSets()
    97  	r.cleanupTypes()
    98  	return &Package{
    99  		Doc:        r.doc,
   100  		Name:       pkg.Name,
   101  		ImportPath: importPath,
   102  		Imports:    sortedKeys(r.imports),
   103  		Filenames:  r.filenames,
   104  		Notes:      r.notes,
   105  		Bugs:       noteBodies(r.notes["BUG"]),
   106  		Consts:     sortedValues(r.values, token.CONST),
   107  		Types:      sortedTypes(r.types, mode&AllMethods != 0),
   108  		Vars:       sortedValues(r.values, token.VAR),
   109  		Funcs:      sortedFuncs(r.funcs, true),
   110  	}
   111  }