libgo/go/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         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 }