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		Bugs       []string
    21	
    22		// declarations
    23		Consts []*Value
    24		Types  []*Type
    25		Vars   []*Value
    26		Funcs  []*Func
    27	}
    28	
    29	// Value is the documentation for a (possibly grouped) var or const declaration.
    30	type Value struct {
    31		Doc   string
    32		Names []string // var or const names in declaration order
    33		Decl  *ast.GenDecl
    34	
    35		order int
    36	}
    37	
    38	// Type is the documentation for a type declaration.
    39	type Type struct {
    40		Doc  string
    41		Name string
    42		Decl *ast.GenDecl
    43	
    44		// associated declarations
    45		Consts  []*Value // sorted list of constants of (mostly) this type
    46		Vars    []*Value // sorted list of variables of (mostly) this type
    47		Funcs   []*Func  // sorted list of functions returning this type
    48		Methods []*Func  // sorted list of methods (including embedded ones) of this type
    49	}
    50	
    51	// Func is the documentation for a func declaration.
    52	type Func struct {
    53		Doc  string
    54		Name string
    55		Decl *ast.FuncDecl
    56	
    57		// methods
    58		// (for functions, these fields have the respective zero value)
    59		Recv  string // actual   receiver "T" or "*T"
    60		Orig  string // original receiver "T" or "*T"
    61		Level int    // embedding level; 0 means not embedded
    62	}
    63	
    64	// Mode values control the operation of New.
    65	type Mode int
    66	
    67	const (
    68		// extract documentation for all package-level declarations,
    69		// not just exported ones
    70		AllDecls Mode = 1 << iota
    71	
    72		// show all embedded methods, not just the ones of
    73		// invisible (unexported) anonymous fields
    74		AllMethods
    75	)
    76	
    77	// New computes the package documentation for the given package AST.
    78	// New takes ownership of the AST pkg and may edit or overwrite it.
    79	//
    80	func New(pkg *ast.Package, importPath string, mode Mode) *Package {
    81		var r reader
    82		r.readPackage(pkg, mode)
    83		r.computeMethodSets()
    84		r.cleanupTypes()
    85		return &Package{
    86			Doc:        r.doc,
    87			Name:       pkg.Name,
    88			ImportPath: importPath,
    89			Imports:    sortedKeys(r.imports),
    90			Filenames:  r.filenames,
    91			Bugs:       r.bugs,
    92			Consts:     sortedValues(r.values, token.CONST),
    93			Types:      sortedTypes(r.types, mode&AllMethods != 0),
    94			Vars:       sortedValues(r.values, token.VAR),
    95			Funcs:      sortedFuncs(r.funcs, true),
    96		}
    97	}