4deda6ea98
* Changes to make vendored packages accept new home. * Fix go2idl to import vendored packages.
113 lines
3.2 KiB
Go
113 lines
3.2 KiB
Go
// 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 (
|
|
"k8s.io/kubernetes/third_party/golang/go/ast"
|
|
"k8s.io/kubernetes/third_party/golang/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),
|
|
}
|
|
}
|