}
type PageInfo struct {
- Dirname string // directory containing the package
- PList []string // list of package names found
- FSet *token.FileSet // corresponding file set
- PAst *ast.File // nil if no single AST with package exports
- PDoc *doc.PackageDoc // nil if no single package documentation
- Examples []*doc.Example // nil if no example code
- Dirs *DirList // nil if no directory information
- DirTime time.Time // directory time stamp
- DirFlat bool // if set, show directory in a flat (non-indented) manner
- IsPkg bool // false if this is not documenting a real package
- Err error // I/O error or nil
+ Dirname string // directory containing the package
+ PList []string // list of package names found
+ FSet *token.FileSet // corresponding file set
+ PAst *ast.File // nil if no single AST with package exports
+ PDoc *doc.Package // nil if no single package documentation
+ Examples []*doc.Example // nil if no example code
+ Dirs *DirList // nil if no directory information
+ DirTime time.Time // directory time stamp
+ DirFlat bool // if set, show directory in a flat (non-indented) manner
+ IsPkg bool // false if this is not documenting a real package
+ Err error // I/O error or nil
}
func (info *PageInfo) IsEmpty() bool {
// compute package documentation
var past *ast.File
- var pdoc *doc.PackageDoc
+ var pdoc *doc.Package
if pkg != nil {
- exportsOnly := mode&noFiltering == 0
+ var docMode doc.Mode
+ if mode&noFiltering != 0 {
+ docMode = doc.AllDecls
+ }
if mode&showSource == 0 {
// show extracted documentation
- pdoc = doc.NewPackageDoc(pkg, path.Clean(relpath), exportsOnly) // no trailing '/' in importpath
+ pdoc = doc.New(pkg, path.Clean(relpath), docMode) // no trailing '/' in importpath
} else {
// show source code
// TODO(gri) Consider eliminating export filtering in this mode,
// or perhaps eliminating the mode altogether.
- if exportsOnly {
+ if docMode&doc.AllDecls == 0 {
ast.PackageExports(pkg)
}
past = ast.MergePackageFiles(pkg, ast.FilterUnassociatedComments)
case info.PDoc != nil:
switch {
case info.IsPkg:
- title = "Package " + info.PDoc.PackageName
- case info.PDoc.PackageName == fakePkgName:
+ title = "Package " + info.PDoc.Name
+ case info.PDoc.Name == fakePkgName:
// assume that the directory name is the command name
_, pkgname := path.Split(relpath)
title = "Command " + pkgname
default:
- title = "Command " + info.PDoc.PackageName
+ title = "Command " + info.PDoc.Name
}
default:
title = "Directory " + relativeURL(info.Dirname)
// Package doc extracts source code documentation from a Go AST.
package doc
-import "go/ast"
+import (
+ "go/ast"
+ "sort"
+)
-// PackageDoc is the documentation for an entire package.
-type PackageDoc struct {
- Doc string
- PackageName string
- ImportPath string
- Filenames []string
- Consts []*ValueDoc
- Types []*TypeDoc
- Vars []*ValueDoc
- Funcs []*FuncDoc
- Bugs []string
+// Package is the documentation for an entire package.
+type Package struct {
+ Doc string
+ Name string
+ ImportPath string
+ Imports []string // TODO(gri) this field is not computed at the moment
+ Filenames []string
+ Consts []*Value
+ Types []*Type
+ Vars []*Value
+ Funcs []*Func
+ Bugs []string
}
// Value is the documentation for a (possibly grouped) var or const declaration.
-type ValueDoc struct {
- Doc string
- Decl *ast.GenDecl
+type Value struct {
+ Doc string
+ Names []string // var or const names in declaration order
+ Decl *ast.GenDecl
order int
}
-// TypeDoc is the documentation for type declaration.
-type TypeDoc struct {
- Doc string
- Type *ast.TypeSpec
- Decl *ast.GenDecl
- Consts []*ValueDoc // sorted list of constants of (mostly) this type
- Vars []*ValueDoc // sorted list of variables of (mostly) this type
- Factories []*FuncDoc // sorted list of functions returning this type
- Methods []*FuncDoc // sorted list of methods (including embedded ones) of this type
+type Method struct {
+ *Func
+ // TODO(gri) The following fields are not set at the moment.
+ Recv *Type // original receiver base type
+ Level int // embedding level; 0 means Func is not embedded
+}
+
+// Type is the documentation for type declaration.
+type Type struct {
+ Doc string
+ Name string
+ Type *ast.TypeSpec
+ Decl *ast.GenDecl
+ 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 []*Method // sorted list of methods (including embedded ones) of this type
- methods []*FuncDoc // top-level methods only
- embedded methodSet // embedded methods only
+ methods []*Func // top-level methods only
+ embedded methodSet // embedded methods only
order int
}
// Func is the documentation for a func declaration.
-type FuncDoc struct {
+type Func struct {
Doc string
- Recv ast.Expr // TODO(rsc): Would like string here
Name string
+ // TODO(gri) remove Recv once we switch to new implementation
+ Recv ast.Expr // TODO(rsc): Would like string here
Decl *ast.FuncDecl
}
-// NewPackageDoc computes the package documentation for the given package
-// and import path. If exportsOnly is set, only exported objects are
-// included in the documentation.
-func NewPackageDoc(pkg *ast.Package, importpath string, exportsOnly bool) *PackageDoc {
+// 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
+)
+
+// New computes the package documentation for the given package.
+func New(pkg *ast.Package, importpath string, mode Mode) *Package {
var r docReader
- r.init(pkg.Name, exportsOnly)
+ r.init(pkg.Name, mode)
filenames := make([]string, len(pkg.Files))
+ // sort package files before reading them so that the
+ // result is the same on different machines (32/64bit)
i := 0
- for filename, f := range pkg.Files {
- if exportsOnly {
+ for filename := range pkg.Files {
+ filenames[i] = filename
+ i++
+ }
+ sort.Strings(filenames)
+
+ // process files in sorted order
+ for _, filename := range filenames {
+ f := pkg.Files[filename]
+ if mode&AllDecls == 0 {
r.fileExports(f)
}
r.addFile(f)
- filenames[i] = filename
- i++
}
return r.newDoc(importpath, filenames)
}
return false
}
-func filterValueDocs(a []*ValueDoc, f Filter) []*ValueDoc {
+func filterValues(a []*Value, f Filter) []*Value {
w := 0
for _, vd := range a {
if matchDecl(vd.Decl, f) {
return a[0:w]
}
-func filterFuncDocs(a []*FuncDoc, f Filter) []*FuncDoc {
+func filterFuncs(a []*Func, f Filter) []*Func {
w := 0
for _, fd := range a {
if f(fd.Name) {
return a[0:w]
}
-func filterTypeDocs(a []*TypeDoc, f Filter) []*TypeDoc {
+func filterMethods(a []*Method, f Filter) []*Method {
+ w := 0
+ for _, md := range a {
+ if f(md.Name) {
+ a[w] = md
+ w++
+ }
+ }
+ return a[0:w]
+}
+
+func filterTypes(a []*Type, f Filter) []*Type {
w := 0
for _, td := range a {
n := 0 // number of matches
n = 1
} else {
// type name doesn't match, but we may have matching consts, vars, factories or methods
- td.Consts = filterValueDocs(td.Consts, f)
- td.Vars = filterValueDocs(td.Vars, f)
- td.Factories = filterFuncDocs(td.Factories, f)
- td.Methods = filterFuncDocs(td.Methods, f)
- n += len(td.Consts) + len(td.Vars) + len(td.Factories) + len(td.Methods)
+ td.Consts = filterValues(td.Consts, f)
+ td.Vars = filterValues(td.Vars, f)
+ td.Funcs = filterFuncs(td.Funcs, f)
+ td.Methods = filterMethods(td.Methods, f)
+ n += len(td.Consts) + len(td.Vars) + len(td.Funcs) + len(td.Methods)
}
if n > 0 {
a[w] = td
// Filter eliminates documentation for names that don't pass through the filter f.
// TODO: Recognize "Type.Method" as a name.
//
-func (p *PackageDoc) Filter(f Filter) {
- p.Consts = filterValueDocs(p.Consts, f)
- p.Vars = filterValueDocs(p.Vars, f)
- p.Types = filterTypeDocs(p.Types, f)
- p.Funcs = filterFuncDocs(p.Funcs, f)
+func (p *Package) Filter(f Filter) {
+ p.Consts = filterValues(p.Consts, f)
+ p.Vars = filterValues(p.Vars, f)
+ p.Types = filterTypes(p.Types, f)
+ p.Funcs = filterFuncs(p.Funcs, f)
p.Doc = "" // don't show top-level package doc
}
// if the type declaration hasn't been seen yet, decl is nil
decl *ast.GenDecl
embedded []embeddedType
- forward *TypeDoc // forward link to processed type documentation
+ forward *Type // forward link to processed type documentation
// declarations associated with the type
values []*ast.GenDecl // consts and vars
// printing the corresponding AST node).
//
type docReader struct {
- doc *ast.CommentGroup // package documentation, if any
- pkgName string
- exportsOnly bool
- values []*ast.GenDecl // consts and vars
- types map[string]*typeInfo
- embedded map[string]*typeInfo // embedded types, possibly not exported
- funcs map[string]*ast.FuncDecl
- bugs []*ast.CommentGroup
+ doc *ast.CommentGroup // package documentation, if any
+ pkgName string
+ mode Mode
+ values []*ast.GenDecl // consts and vars
+ types map[string]*typeInfo
+ embedded map[string]*typeInfo // embedded types, possibly not exported
+ funcs map[string]*ast.FuncDecl
+ bugs []*ast.CommentGroup
}
-func (doc *docReader) init(pkgName string, exportsOnly bool) {
+func (doc *docReader) init(pkgName string, mode Mode) {
doc.pkgName = pkgName
- doc.exportsOnly = exportsOnly
+ doc.mode = mode
doc.types = make(map[string]*typeInfo)
doc.embedded = make(map[string]*typeInfo)
doc.funcs = make(map[string]*ast.FuncDecl)
// TODO(gri): Consider just collecting the TypeSpec
// node (and copy in the GenDecl.doc if there is no
// doc in the TypeSpec - this is currently done in
- // makeTypeDocs below). Simpler data structures, but
+ // makeTypes below). Simpler data structures, but
// would lose GenDecl documentation if the TypeSpec
// has documentation as well.
fake := &ast.GenDecl{d.Doc, d.Pos(), token.TYPE, token.NoPos,
// ----------------------------------------------------------------------------
// Conversion to external representation
-type sortValueDoc []*ValueDoc
+type sortValue []*Value
-func (p sortValueDoc) Len() int { return len(p) }
-func (p sortValueDoc) Swap(i, j int) { p[i], p[j] = p[j], p[i] }
+func (p sortValue) Len() int { return len(p) }
+func (p sortValue) Swap(i, j int) { p[i], p[j] = p[j], p[i] }
func declName(d *ast.GenDecl) string {
if len(d.Specs) != 1 {
return ""
}
-func (p sortValueDoc) Less(i, j int) bool {
+func (p sortValue) Less(i, j int) bool {
// sort by name
// pull blocks (name = "") up to top
// in original order
return p[i].order < p[j].order
}
-func makeValueDocs(list []*ast.GenDecl, tok token.Token) []*ValueDoc {
- d := make([]*ValueDoc, len(list)) // big enough in any case
+func specNames(specs []ast.Spec) []string {
+ names := make([]string, len(specs)) // reasonable estimate
+ for _, s := range specs {
+ // should always be an *ast.ValueSpec, but be careful
+ if s, ok := s.(*ast.ValueSpec); ok {
+ for _, ident := range s.Names {
+ names = append(names, ident.Name)
+ }
+ }
+ }
+ return names
+}
+
+func makeValues(list []*ast.GenDecl, tok token.Token) []*Value {
+ d := make([]*Value, len(list)) // big enough in any case
n := 0
for i, decl := range list {
if decl.Tok == tok {
- d[n] = &ValueDoc{decl.Doc.Text(), decl, i}
+ d[n] = &Value{decl.Doc.Text(), specNames(decl.Specs), decl, i}
n++
decl.Doc = nil // doc consumed - removed from AST
}
}
d = d[0:n]
- sort.Sort(sortValueDoc(d))
+ sort.Sort(sortValue(d))
return d
}
-type sortFuncDoc []*FuncDoc
+type sortFunc []*Func
-func (p sortFuncDoc) Len() int { return len(p) }
-func (p sortFuncDoc) Swap(i, j int) { p[i], p[j] = p[j], p[i] }
-func (p sortFuncDoc) Less(i, j int) bool { return p[i].Name < p[j].Name }
+func (p sortFunc) Len() int { return len(p) }
+func (p sortFunc) Swap(i, j int) { p[i], p[j] = p[j], p[i] }
+func (p sortFunc) Less(i, j int) bool { return p[i].Name < p[j].Name }
-func makeFuncDocs(m map[string]*ast.FuncDecl) []*FuncDoc {
- d := make([]*FuncDoc, len(m))
+func makeFuncs(m map[string]*ast.FuncDecl) []*Func {
+ d := make([]*Func, len(m))
i := 0
for _, f := range m {
- doc := new(FuncDoc)
+ doc := new(Func)
doc.Doc = f.Doc.Text()
f.Doc = nil // doc consumed - remove from ast.FuncDecl node
if f.Recv != nil {
d[i] = doc
i++
}
- sort.Sort(sortFuncDoc(d))
+ sort.Sort(sortFunc(d))
return d
}
-type methodSet map[string]*FuncDoc
+type methodSet map[string]*Func
-func (mset methodSet) add(m *FuncDoc) {
+func (mset methodSet) add(m *Func) {
if mset[m.Name] == nil {
mset[m.Name] = m
}
}
-func (mset methodSet) sortedList() []*FuncDoc {
- list := make([]*FuncDoc, len(mset))
+type sortMethod []*Method
+
+func (p sortMethod) Len() int { return len(p) }
+func (p sortMethod) Swap(i, j int) { p[i], p[j] = p[j], p[i] }
+func (p sortMethod) Less(i, j int) bool { return p[i].Func.Name < p[j].Func.Name }
+
+func (mset methodSet) sortedList() []*Method {
+ list := make([]*Method, len(mset))
i := 0
for _, m := range mset {
- list[i] = m
+ list[i] = &Method{Func: m}
i++
}
- sort.Sort(sortFuncDoc(list))
+ sort.Sort(sortMethod(list))
return list
}
-type sortTypeDoc []*TypeDoc
+type sortType []*Type
-func (p sortTypeDoc) Len() int { return len(p) }
-func (p sortTypeDoc) Swap(i, j int) { p[i], p[j] = p[j], p[i] }
-func (p sortTypeDoc) Less(i, j int) bool {
+func (p sortType) Len() int { return len(p) }
+func (p sortType) Swap(i, j int) { p[i], p[j] = p[j], p[i] }
+func (p sortType) Less(i, j int) bool {
// sort by name
// pull blocks (name = "") up to top
// in original order
// NOTE(rsc): This would appear not to be correct for type ( )
// blocks, but the doc extractor above has split them into
// individual declarations.
-func (doc *docReader) makeTypeDocs(m map[string]*typeInfo) []*TypeDoc {
+func (doc *docReader) makeTypes(m map[string]*typeInfo) []*Type {
// TODO(gri) Consider computing the embedded method information
- // before calling makeTypeDocs. Then this function can
+ // before calling makeTypes. Then this function can
// be single-phased again. Also, it might simplify some
// of the logic.
//
- // phase 1: associate collected declarations with TypeDocs
- list := make([]*TypeDoc, len(m))
+ // phase 1: associate collected declarations with Types
+ list := make([]*Type, len(m))
i := 0
for _, old := range m {
// old typeInfos may not have a declaration associated with them
if decl := old.decl; decl != nil || !old.exported() {
// process the type even if not exported so that we have
// its methods in case they are embedded somewhere
- t := new(TypeDoc)
+ t := new(Type)
if decl != nil {
typespec := decl.Specs[0].(*ast.TypeSpec)
doc := typespec.Doc
t.Doc = doc.Text()
t.Type = typespec
}
- t.Consts = makeValueDocs(old.values, token.CONST)
- t.Vars = makeValueDocs(old.values, token.VAR)
- t.Factories = makeFuncDocs(old.factories)
- t.methods = makeFuncDocs(old.methods)
+ t.Consts = makeValues(old.values, token.CONST)
+ t.Vars = makeValues(old.values, token.VAR)
+ t.Funcs = makeFuncs(old.factories)
+ t.methods = makeFuncs(old.methods)
// The list of embedded types' methods is computed from the list
// of embedded types, some of which may not have been processed
// yet (i.e., their forward link is nil) - do this in a 2nd phase.
old.forward = t // old has been processed
// only add the type to the final type list if it
// is exported or if we want to see all types
- if old.exported() || !doc.exportsOnly {
+ if old.exported() || doc.mode&AllDecls != 0 {
list[i] = t
i++
}
}
}
- // phase 3: compute final method set for each TypeDoc
+ // phase 3: compute final method set for each Type
for _, d := range list {
if len(d.embedded) > 0 {
// there are embedded methods - exclude
}
d.Methods = mset.sortedList()
} else {
- // no embedded methods
- d.Methods = d.methods
+ // no embedded methods - convert into a Method list
+ d.Methods = make([]*Method, len(d.methods))
+ for i, m := range d.methods {
+ d.Methods[i] = &Method{Func: m}
+ }
}
}
- sort.Sort(sortTypeDoc(list))
+ sort.Sort(sortType(list))
return list
}
}
}
-func customizeRecv(m *FuncDoc, embeddedIsPtr bool, recvTypeName string) *FuncDoc {
+func customizeRecv(m *Func, embeddedIsPtr bool, recvTypeName string) *Func {
if m == nil || m.Decl == nil || m.Decl.Recv == nil || len(m.Decl.Recv.List) != 1 {
return m // shouldn't happen, but be safe
}
return &newM
}
-func makeBugDocs(list []*ast.CommentGroup) []string {
+func makeBugs(list []*ast.CommentGroup) []string {
d := make([]string, len(list))
for i, g := range list {
d[i] = g.Text()
// newDoc returns the accumulated documentation for the package.
//
-func (doc *docReader) newDoc(importpath string, filenames []string) *PackageDoc {
- p := new(PackageDoc)
- p.PackageName = doc.pkgName
+func (doc *docReader) newDoc(importpath string, filenames []string) *Package {
+ p := new(Package)
+ p.Name = doc.pkgName
p.ImportPath = importpath
sort.Strings(filenames)
p.Filenames = filenames
p.Doc = doc.doc.Text()
- // makeTypeDocs may extend the list of doc.values and
+ // makeTypes may extend the list of doc.values and
// doc.funcs and thus must be called before any other
// function consuming those lists
- p.Types = doc.makeTypeDocs(doc.types)
- p.Consts = makeValueDocs(doc.values, token.CONST)
- p.Vars = makeValueDocs(doc.values, token.VAR)
- p.Funcs = makeFuncDocs(doc.funcs)
- p.Bugs = makeBugDocs(doc.bugs)
+ p.Types = doc.makeTypes(doc.types)
+ p.Consts = makeValues(doc.values, token.CONST)
+ p.Vars = makeValues(doc.values, token.VAR)
+ p.Funcs = makeFuncs(doc.funcs)
+ p.Bugs = makeBugs(doc.bugs)
return p
}