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
  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 }