summaryrefslogtreecommitdiff
path: root/src/pkg/go/doc/doc.go
diff options
context:
space:
mode:
Diffstat (limited to 'src/pkg/go/doc/doc.go')
-rw-r--r--src/pkg/go/doc/doc.go390
1 files changed, 195 insertions, 195 deletions
diff --git a/src/pkg/go/doc/doc.go b/src/pkg/go/doc/doc.go
index b7cc8f3b0..be03ddfd6 100644
--- a/src/pkg/go/doc/doc.go
+++ b/src/pkg/go/doc/doc.go
@@ -6,11 +6,11 @@
package doc
import (
- "container/vector";
- "go/ast";
- "go/token";
- "regexp";
- "sort";
+ "container/vector"
+ "go/ast"
+ "go/token"
+ "regexp"
+ "sort"
)
@@ -19,11 +19,11 @@ import (
type typeDoc struct {
// len(decl.Specs) == 1, and the element type is *ast.TypeSpec
// if the type declaration hasn't been seen yet, decl is nil
- decl *ast.GenDecl;
+ decl *ast.GenDecl
// values, factory functions, and methods associated with the type
- values *vector.Vector; // list of *ast.GenDecl (consts and vars)
- factories map[string]*ast.FuncDecl;
- methods map[string]*ast.FuncDecl;
+ values *vector.Vector // list of *ast.GenDecl (consts and vars)
+ factories map[string]*ast.FuncDecl
+ methods map[string]*ast.FuncDecl
}
@@ -35,27 +35,27 @@ type typeDoc struct {
// printing the corresponding AST node).
//
type docReader struct {
- doc *ast.CommentGroup; // package documentation, if any
- pkgName string;
- values *vector.Vector; // list of *ast.GenDecl (consts and vars)
- types map[string]*typeDoc;
- funcs map[string]*ast.FuncDecl;
- bugs *vector.Vector; // list of *ast.CommentGroup
+ doc *ast.CommentGroup // package documentation, if any
+ pkgName string
+ values *vector.Vector // list of *ast.GenDecl (consts and vars)
+ types map[string]*typeDoc
+ funcs map[string]*ast.FuncDecl
+ bugs *vector.Vector // list of *ast.CommentGroup
}
func (doc *docReader) init(pkgName string) {
- doc.pkgName = pkgName;
- doc.values = new(vector.Vector);
- doc.types = make(map[string]*typeDoc);
- doc.funcs = make(map[string]*ast.FuncDecl);
- doc.bugs = new(vector.Vector);
+ doc.pkgName = pkgName
+ doc.values = new(vector.Vector)
+ doc.types = make(map[string]*typeDoc)
+ doc.funcs = make(map[string]*ast.FuncDecl)
+ doc.bugs = new(vector.Vector)
}
func (doc *docReader) addType(decl *ast.GenDecl) {
- spec := decl.Specs[0].(*ast.TypeSpec);
- typ := doc.lookupTypeDoc(spec.Name.Value);
+ spec := decl.Specs[0].(*ast.TypeSpec)
+ typ := doc.lookupTypeDoc(spec.Name.Value)
// typ should always be != nil since declared types
// are always named - be conservative and check
if typ != nil {
@@ -68,15 +68,15 @@ func (doc *docReader) addType(decl *ast.GenDecl) {
func (doc *docReader) lookupTypeDoc(name string) *typeDoc {
if name == "" {
- return nil // no type docs for anonymous types
+ return nil // no type docs for anonymous types
}
if tdoc, found := doc.types[name]; found {
return tdoc
}
// type wasn't found - add one without declaration
- tdoc := &typeDoc{nil, new(vector.Vector), make(map[string]*ast.FuncDecl), make(map[string]*ast.FuncDecl)};
- doc.types[name] = tdoc;
- return tdoc;
+ tdoc := &typeDoc{nil, new(vector.Vector), make(map[string]*ast.FuncDecl), make(map[string]*ast.FuncDecl)}
+ doc.types[name] = tdoc
+ return tdoc
}
@@ -91,7 +91,7 @@ func baseTypeName(typ ast.Expr) string {
case *ast.StarExpr:
return baseTypeName(t.X)
}
- return "";
+ return ""
}
@@ -100,12 +100,12 @@ func (doc *docReader) addValue(decl *ast.GenDecl) {
// Heuristic: For each typed entry, determine the type name, if any.
// If there is exactly one type name that is sufficiently
// frequent, associate the decl with the respective type.
- domName := "";
- domFreq := 0;
- prev := "";
+ domName := ""
+ domFreq := 0
+ prev := ""
for _, s := range decl.Specs {
if v, ok := s.(*ast.ValueSpec); ok {
- name := "";
+ name := ""
switch {
case v.Type != nil:
// a type is present; determine it's name
@@ -122,38 +122,38 @@ func (doc *docReader) addValue(decl *ast.GenDecl) {
if domName != "" && domName != name {
// more than one type name - do not associate
// with any type
- domName = "";
- break;
+ domName = ""
+ break
}
- domName = name;
- domFreq++;
+ domName = name
+ domFreq++
}
- prev = name;
+ prev = name
}
}
// determine values list
- const threshold = 0.75;
- values := doc.values;
+ const threshold = 0.75
+ values := doc.values
if domName != "" && domFreq >= int(float(len(decl.Specs))*threshold) {
// typed entries are sufficiently frequent
- typ := doc.lookupTypeDoc(domName);
+ typ := doc.lookupTypeDoc(domName)
if typ != nil {
- values = typ.values // associate with that type
+ values = typ.values // associate with that type
}
}
- values.Push(decl);
+ values.Push(decl)
}
func (doc *docReader) addFunc(fun *ast.FuncDecl) {
- name := fun.Name.Value;
+ name := fun.Name.Value
// determine if it should be associated with a type
if fun.Recv != nil {
// method
- typ := doc.lookupTypeDoc(baseTypeName(fun.Recv.Type));
+ typ := doc.lookupTypeDoc(baseTypeName(fun.Recv.Type))
if typ != nil {
// exported receiver type
typ.methods[name] = fun
@@ -163,19 +163,19 @@ func (doc *docReader) addFunc(fun *ast.FuncDecl) {
// that can be called because of exported values (consts, vars, or
// function results) of that type. Could determine if that is the
// case and then show those methods in an appropriate section.
- return;
+ return
}
// perhaps a factory function
// determine result type, if any
if len(fun.Type.Results) >= 1 {
- res := fun.Type.Results[0];
+ res := fun.Type.Results[0]
if len(res.Names) <= 1 {
// exactly one (named or anonymous) result associated
// with the first type in result signature (there may
// be more than one result)
- tname := baseTypeName(res.Type);
- typ := doc.lookupTypeDoc(tname);
+ tname := baseTypeName(res.Type)
+ typ := doc.lookupTypeDoc(tname)
if typ != nil {
// named and exported result type
@@ -187,18 +187,18 @@ func (doc *docReader) addFunc(fun *ast.FuncDecl) {
if doc.pkgName == "os" && tname == "Error" &&
name != "NewError" && name != "NewSyscallError" {
// not a factory function for os.Error
- doc.funcs[name] = fun; // treat as ordinary function
- return;
+ doc.funcs[name] = fun // treat as ordinary function
+ return
}
- typ.factories[name] = fun;
- return;
+ typ.factories[name] = fun
+ return
}
}
}
// ordinary function
- doc.funcs[name] = fun;
+ doc.funcs[name] = fun
}
@@ -212,7 +212,7 @@ func (doc *docReader) addDecl(decl ast.Decl) {
doc.addValue(d)
case token.TYPE:
// types are handled individually
- var noPos token.Position;
+ var noPos token.Position
for _, spec := range d.Specs {
// make a (fake) GenDecl node for this TypeSpec
// (we need to do this here - as opposed to just
@@ -237,17 +237,17 @@ func (doc *docReader) addDecl(decl ast.Decl) {
func copyCommentList(list []*ast.Comment) []*ast.Comment {
- copy := make([]*ast.Comment, len(list));
+ copy := make([]*ast.Comment, len(list))
for i, c := range list {
copy[i] = c
}
- return copy;
+ return copy
}
var (
- bug_markers = regexp.MustCompile("^/[/*][ \t]*BUG\\(.*\\):[ \t]*"); // BUG(uid):
- bug_content = regexp.MustCompile("[^ \n\r\t]+"); // at least one non-whitespace char
+ bug_markers = regexp.MustCompile("^/[/*][ \t]*BUG\\(.*\\):[ \t]*") // BUG(uid):
+ bug_content = regexp.MustCompile("[^ \n\r\t]+") // at least one non-whitespace char
)
@@ -262,8 +262,8 @@ func (doc *docReader) addFile(src *ast.File) {
// using ast.MergePackageFiles which handles these
// comments correctly (but currently looses BUG(...)
// comments).
- doc.doc = src.Doc;
- src.Doc = nil; // doc consumed - remove from ast.File node
+ doc.doc = src.Doc
+ src.Doc = nil // doc consumed - remove from ast.File node
}
// add all declarations
@@ -273,41 +273,41 @@ func (doc *docReader) addFile(src *ast.File) {
// collect BUG(...) comments
for c := src.Comments; c != nil; c = c.Next {
- text := c.List[0].Text;
- cstr := string(text);
+ text := c.List[0].Text
+ cstr := string(text)
if m := bug_markers.ExecuteString(cstr); len(m) > 0 {
// found a BUG comment; maybe empty
if bstr := cstr[m[1]:]; bug_content.MatchString(bstr) {
// non-empty BUG comment; collect comment without BUG prefix
- list := copyCommentList(c.List);
- list[0].Text = text[m[1]:];
- doc.bugs.Push(&ast.CommentGroup{list, nil});
+ list := copyCommentList(c.List)
+ list[0].Text = text[m[1]:]
+ doc.bugs.Push(&ast.CommentGroup{list, nil})
}
}
}
- src.Comments = nil; // consumed unassociated comments - remove from ast.File node
+ src.Comments = nil // consumed unassociated comments - remove from ast.File node
}
func NewFileDoc(file *ast.File) *PackageDoc {
- var r docReader;
- r.init(file.Name.Value);
- r.addFile(file);
- return r.newDoc("", "", nil);
+ var r docReader
+ r.init(file.Name.Value)
+ r.addFile(file)
+ return r.newDoc("", "", nil)
}
func NewPackageDoc(pkg *ast.Package, importpath string) *PackageDoc {
- var r docReader;
- r.init(pkg.Name);
- filenames := make([]string, len(pkg.Files));
- i := 0;
+ var r docReader
+ r.init(pkg.Name)
+ filenames := make([]string, len(pkg.Files))
+ i := 0
for filename, f := range pkg.Files {
- r.addFile(f);
- filenames[i] = filename;
- i++;
+ r.addFile(f)
+ filenames[i] = filename
+ i++
}
- return r.newDoc(importpath, pkg.Path, filenames);
+ return r.newDoc(importpath, pkg.Path, filenames)
}
@@ -318,15 +318,15 @@ func NewPackageDoc(pkg *ast.Package, importpath string) *PackageDoc {
// values, either vars or consts.
//
type ValueDoc struct {
- Doc string;
- Decl *ast.GenDecl;
- order int;
+ Doc string
+ Decl *ast.GenDecl
+ order int
}
type sortValueDoc []*ValueDoc
-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 sortValueDoc) Len() int { return len(p) }
+func (p sortValueDoc) Swap(i, j int) { p[i], p[j] = p[j], p[i] }
func declName(d *ast.GenDecl) string {
@@ -341,7 +341,7 @@ func declName(d *ast.GenDecl) string {
return v.Name.Value
}
- return "";
+ return ""
}
@@ -352,24 +352,24 @@ func (p sortValueDoc) Less(i, j int) bool {
if ni, nj := declName(p[i].Decl), declName(p[j].Decl); ni != nj {
return ni < nj
}
- return p[i].order < p[j].order;
+ return p[i].order < p[j].order
}
func makeValueDocs(v *vector.Vector, tok token.Token) []*ValueDoc {
- d := make([]*ValueDoc, v.Len()); // big enough in any case
- n := 0;
+ d := make([]*ValueDoc, v.Len()) // big enough in any case
+ n := 0
for i := range d {
- decl := v.At(i).(*ast.GenDecl);
+ decl := v.At(i).(*ast.GenDecl)
if decl.Tok == tok {
- d[n] = &ValueDoc{CommentText(decl.Doc), decl, i};
- n++;
- decl.Doc = nil; // doc consumed - removed from AST
+ d[n] = &ValueDoc{CommentText(decl.Doc), decl, i}
+ n++
+ decl.Doc = nil // doc consumed - removed from AST
}
}
- d = d[0:n];
- sort.Sort(sortValueDoc(d));
- return d;
+ d = d[0:n]
+ sort.Sort(sortValueDoc(d))
+ return d
}
@@ -377,36 +377,36 @@ func makeValueDocs(v *vector.Vector, tok token.Token) []*ValueDoc {
// either a top-level function or a method function.
//
type FuncDoc struct {
- Doc string;
- Recv ast.Expr; // TODO(rsc): Would like string here
- Name string;
- Decl *ast.FuncDecl;
+ Doc string
+ Recv ast.Expr // TODO(rsc): Would like string here
+ Name string
+ Decl *ast.FuncDecl
}
type sortFuncDoc []*FuncDoc
-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 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 makeFuncDocs(m map[string]*ast.FuncDecl) []*FuncDoc {
- d := make([]*FuncDoc, len(m));
- i := 0;
+ d := make([]*FuncDoc, len(m))
+ i := 0
for _, f := range m {
- doc := new(FuncDoc);
- doc.Doc = CommentText(f.Doc);
- f.Doc = nil; // doc consumed - remove from ast.FuncDecl node
+ doc := new(FuncDoc)
+ doc.Doc = CommentText(f.Doc)
+ f.Doc = nil // doc consumed - remove from ast.FuncDecl node
if f.Recv != nil {
doc.Recv = f.Recv.Type
}
- doc.Name = f.Name.Value;
- doc.Decl = f;
- d[i] = doc;
- i++;
+ doc.Name = f.Name.Value
+ doc.Decl = f
+ d[i] = doc
+ i++
}
- sort.Sort(sortFuncDoc(d));
- return d;
+ sort.Sort(sortFuncDoc(d))
+ return d
}
@@ -415,20 +415,20 @@ func makeFuncDocs(m map[string]*ast.FuncDecl) []*FuncDoc {
// Factories is a sorted list of factory functions that return that type.
// Methods is a sorted list of method functions on that type.
type TypeDoc struct {
- Doc string;
- Type *ast.TypeSpec;
- Consts []*ValueDoc;
- Vars []*ValueDoc;
- Factories []*FuncDoc;
- Methods []*FuncDoc;
- Decl *ast.GenDecl;
- order int;
+ Doc string
+ Type *ast.TypeSpec
+ Consts []*ValueDoc
+ Vars []*ValueDoc
+ Factories []*FuncDoc
+ Methods []*FuncDoc
+ Decl *ast.GenDecl
+ order int
}
type sortTypeDoc []*TypeDoc
-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) 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 {
// sort by name
// pull blocks (name = "") up to top
@@ -436,7 +436,7 @@ func (p sortTypeDoc) Less(i, j int) bool {
if ni, nj := p[i].Type.Name.Value, p[j].Type.Name.Value; ni != nj {
return ni < nj
}
- return p[i].order < p[j].order;
+ return p[i].order < p[j].order
}
@@ -444,32 +444,32 @@ func (p sortTypeDoc) Less(i, j int) bool {
// blocks, but the doc extractor above has split them into
// individual declarations.
func (doc *docReader) makeTypeDocs(m map[string]*typeDoc) []*TypeDoc {
- d := make([]*TypeDoc, len(m));
- i := 0;
+ d := make([]*TypeDoc, len(m))
+ i := 0
for _, old := range m {
// all typeDocs should have a declaration associated with
// them after processing an entire package - be conservative
// and check
if decl := old.decl; decl != nil {
- typespec := decl.Specs[0].(*ast.TypeSpec);
- t := new(TypeDoc);
- doc := typespec.Doc;
- typespec.Doc = nil; // doc consumed - remove from ast.TypeSpec node
+ typespec := decl.Specs[0].(*ast.TypeSpec)
+ t := new(TypeDoc)
+ doc := typespec.Doc
+ typespec.Doc = nil // doc consumed - remove from ast.TypeSpec node
if doc == nil {
// no doc associated with the spec, use the declaration doc, if any
doc = decl.Doc
}
- decl.Doc = nil; // doc consumed - remove from ast.Decl node
- t.Doc = CommentText(doc);
- 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.Decl = old.decl;
- t.order = i;
- d[i] = t;
- i++;
+ decl.Doc = nil // doc consumed - remove from ast.Decl node
+ t.Doc = CommentText(doc)
+ 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.Decl = old.decl
+ t.order = i
+ d[i] = t
+ i++
} else {
// no corresponding type declaration found - move any associated
// values, factory functions, and methods back to the top-level
@@ -477,7 +477,7 @@ func (doc *docReader) makeTypeDocs(m map[string]*typeDoc) []*TypeDoc {
// file containing the explicit type declaration is missing or if
// an unqualified type name was used after a "." import)
// 1) move values
- doc.values.AppendVector(old.values);
+ doc.values.AppendVector(old.values)
// 2) move factory functions
for name, f := range old.factories {
doc.funcs[name] = f
@@ -491,56 +491,56 @@ func (doc *docReader) makeTypeDocs(m map[string]*typeDoc) []*TypeDoc {
}
}
}
- d = d[0:i]; // some types may have been ignored
- sort.Sort(sortTypeDoc(d));
- return d;
+ d = d[0:i] // some types may have been ignored
+ sort.Sort(sortTypeDoc(d))
+ return d
}
func makeBugDocs(v *vector.Vector) []string {
- d := make([]string, v.Len());
+ d := make([]string, v.Len())
for i := 0; i < v.Len(); i++ {
d[i] = CommentText(v.At(i).(*ast.CommentGroup))
}
- return d;
+ return d
}
// PackageDoc is the documentation for an entire package.
//
type PackageDoc struct {
- PackageName string;
- ImportPath string;
- FilePath string;
- Filenames []string;
- Doc string;
- Consts []*ValueDoc;
- Types []*TypeDoc;
- Vars []*ValueDoc;
- Funcs []*FuncDoc;
- Bugs []string;
+ PackageName string
+ ImportPath string
+ FilePath string
+ Filenames []string
+ Doc string
+ Consts []*ValueDoc
+ Types []*TypeDoc
+ Vars []*ValueDoc
+ Funcs []*FuncDoc
+ Bugs []string
}
// newDoc returns the accumulated documentation for the package.
//
func (doc *docReader) newDoc(importpath, filepath string, filenames []string) *PackageDoc {
- p := new(PackageDoc);
- p.PackageName = doc.pkgName;
- p.ImportPath = importpath;
- p.FilePath = filepath;
- sort.SortStrings(filenames);
- p.Filenames = filenames;
- p.Doc = CommentText(doc.doc);
+ p := new(PackageDoc)
+ p.PackageName = doc.pkgName
+ p.ImportPath = importpath
+ p.FilePath = filepath
+ sort.SortStrings(filenames)
+ p.Filenames = filenames
+ p.Doc = CommentText(doc.doc)
// makeTypeDocs 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);
- return p;
+ 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)
+ return p
}
@@ -549,7 +549,7 @@ func (doc *docReader) newDoc(importpath, filepath string, filenames []string) *P
// Does s look like a regular expression?
func isRegexp(s string) bool {
- metachars := ".(|)*+?^$[]";
+ metachars := ".(|)*+?^$[]"
for _, c := range s {
for _, m := range metachars {
if c == m {
@@ -557,7 +557,7 @@ func isRegexp(s string) bool {
}
}
}
- return false;
+ return false
}
@@ -572,7 +572,7 @@ func match(s string, names []string) bool {
return true
}
}
- return false;
+ return false
}
@@ -591,54 +591,54 @@ func matchDecl(d *ast.GenDecl, names []string) bool {
}
}
}
- return false;
+ return false
}
func filterValueDocs(a []*ValueDoc, names []string) []*ValueDoc {
- w := 0;
+ w := 0
for _, vd := range a {
if matchDecl(vd.Decl, names) {
- a[w] = vd;
- w++;
+ a[w] = vd
+ w++
}
}
- return a[0:w];
+ return a[0:w]
}
func filterFuncDocs(a []*FuncDoc, names []string) []*FuncDoc {
- w := 0;
+ w := 0
for _, fd := range a {
if match(fd.Name, names) {
- a[w] = fd;
- w++;
+ a[w] = fd
+ w++
}
}
- return a[0:w];
+ return a[0:w]
}
func filterTypeDocs(a []*TypeDoc, names []string) []*TypeDoc {
- w := 0;
+ w := 0
for _, td := range a {
- n := 0; // number of matches
+ n := 0 // number of matches
if matchDecl(td.Decl, names) {
n = 1
} else {
// type name doesn't match, but we may have matching consts, vars, factories or methods
- td.Consts = filterValueDocs(td.Consts, names);
- td.Vars = filterValueDocs(td.Vars, names);
- td.Factories = filterFuncDocs(td.Factories, names);
- td.Methods = filterFuncDocs(td.Methods, names);
- n += len(td.Consts) + len(td.Vars) + len(td.Factories) + len(td.Methods);
+ td.Consts = filterValueDocs(td.Consts, names)
+ td.Vars = filterValueDocs(td.Vars, names)
+ td.Factories = filterFuncDocs(td.Factories, names)
+ td.Methods = filterFuncDocs(td.Methods, names)
+ n += len(td.Consts) + len(td.Vars) + len(td.Factories) + len(td.Methods)
}
if n > 0 {
- a[w] = td;
- w++;
+ a[w] = td
+ w++
}
}
- return a[0:w];
+ return a[0:w]
}
@@ -648,9 +648,9 @@ func filterTypeDocs(a []*TypeDoc, names []string) []*TypeDoc {
// TODO(r): maybe precompile the regexps.
//
func (p *PackageDoc) Filter(names []string) {
- p.Consts = filterValueDocs(p.Consts, names);
- p.Vars = filterValueDocs(p.Vars, names);
- p.Types = filterTypeDocs(p.Types, names);
- p.Funcs = filterFuncDocs(p.Funcs, names);
- p.Doc = ""; // don't show top-level package doc
+ p.Consts = filterValueDocs(p.Consts, names)
+ p.Vars = filterValueDocs(p.Vars, names)
+ p.Types = filterTypeDocs(p.Types, names)
+ p.Funcs = filterFuncDocs(p.Funcs, names)
+ p.Doc = "" // don't show top-level package doc
}