...
Run Format

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

View as plain text