...
Run Format

Source file src/pkg/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	}
   112	

View as plain text