...
Run Format

Source file src/go/doc/doc.go

Documentation: go/doc

  // Copyright 2009 The Go Authors. All rights reserved.
  // Use of this source code is governed by a BSD-style
  // license that can be found in the LICENSE file.
  
  // Package doc extracts source code documentation from a Go AST.
  package doc
  
  import (
  	"go/ast"
  	"go/token"
  )
  
  // Package is the documentation for an entire package.
  type Package struct {
  	Doc        string
  	Name       string
  	ImportPath string
  	Imports    []string
  	Filenames  []string
  	Notes      map[string][]*Note
  
  	// Deprecated: For backward compatibility Bugs is still populated,
  	// but all new code should use Notes instead.
  	Bugs []string
  
  	// declarations
  	Consts []*Value
  	Types  []*Type
  	Vars   []*Value
  	Funcs  []*Func
  }
  
  // Value is the documentation for a (possibly grouped) var or const declaration.
  type Value struct {
  	Doc   string
  	Names []string // var or const names in declaration order
  	Decl  *ast.GenDecl
  
  	order int
  }
  
  // Type is the documentation for a type declaration.
  type Type struct {
  	Doc  string
  	Name string
  	Decl *ast.GenDecl
  
  	// associated declarations
  	Consts  []*Value // sorted list of constants of (mostly) this type
  	Vars    []*Value // sorted list of variables of (mostly) this type
  	Funcs   []*Func  // sorted list of functions returning this type
  	Methods []*Func  // sorted list of methods (including embedded ones) of this type
  }
  
  // Func is the documentation for a func declaration.
  type Func struct {
  	Doc  string
  	Name string
  	Decl *ast.FuncDecl
  
  	// methods
  	// (for functions, these fields have the respective zero value)
  	Recv  string // actual   receiver "T" or "*T"
  	Orig  string // original receiver "T" or "*T"
  	Level int    // embedding level; 0 means not embedded
  }
  
  // A Note represents a marked comment starting with "MARKER(uid): note body".
  // Any note with a marker of 2 or more upper case [A-Z] letters and a uid of
  // at least one character is recognized. The ":" following the uid is optional.
  // Notes are collected in the Package.Notes map indexed by the notes marker.
  type Note struct {
  	Pos, End token.Pos // position range of the comment containing the marker
  	UID      string    // uid found with the marker
  	Body     string    // note body text
  }
  
  // Mode values control the operation of New.
  type Mode int
  
  const (
  	// extract documentation for all package-level declarations,
  	// not just exported ones
  	AllDecls Mode = 1 << iota
  
  	// show all embedded methods, not just the ones of
  	// invisible (unexported) anonymous fields
  	AllMethods
  )
  
  // New computes the package documentation for the given package AST.
  // New takes ownership of the AST pkg and may edit or overwrite it.
  //
  func New(pkg *ast.Package, importPath string, mode Mode) *Package {
  	var r reader
  	r.readPackage(pkg, mode)
  	r.computeMethodSets()
  	r.cleanupTypes()
  	return &Package{
  		Doc:        r.doc,
  		Name:       pkg.Name,
  		ImportPath: importPath,
  		Imports:    sortedKeys(r.imports),
  		Filenames:  r.filenames,
  		Notes:      r.notes,
  		Bugs:       noteBodies(r.notes["BUG"]),
  		Consts:     sortedValues(r.values, token.CONST),
  		Types:      sortedTypes(r.types, mode&AllMethods != 0),
  		Vars:       sortedValues(r.values, token.VAR),
  		Funcs:      sortedFuncs(r.funcs, true),
  	}
  }
  

View as plain text