Source file src/go/doc/reader.go

Documentation: go/doc

     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
     6  
     7  import (
     8  	"go/ast"
     9  	"go/token"
    10  	"internal/lazyregexp"
    11  	"sort"
    12  	"strconv"
    13  )
    14  
    15  // ----------------------------------------------------------------------------
    16  // function/method sets
    17  //
    18  // Internally, we treat functions like methods and collect them in method sets.
    19  
    20  // A methodSet describes a set of methods. Entries where Decl == nil are conflict
    21  // entries (more than one method with the same name at the same embedding level).
    22  //
    23  type methodSet map[string]*Func
    24  
    25  // recvString returns a string representation of recv of the
    26  // form "T", "*T", or "BADRECV" (if not a proper receiver type).
    27  //
    28  func recvString(recv ast.Expr) string {
    29  	switch t := recv.(type) {
    30  	case *ast.Ident:
    31  		return t.Name
    32  	case *ast.StarExpr:
    33  		return "*" + recvString(t.X)
    34  	}
    35  	return "BADRECV"
    36  }
    37  
    38  // set creates the corresponding Func for f and adds it to mset.
    39  // If there are multiple f's with the same name, set keeps the first
    40  // one with documentation; conflicts are ignored. The boolean
    41  // specifies whether to leave the AST untouched.
    42  //
    43  func (mset methodSet) set(f *ast.FuncDecl, preserveAST bool) {
    44  	name := f.Name.Name
    45  	if g := mset[name]; g != nil && g.Doc != "" {
    46  		// A function with the same name has already been registered;
    47  		// since it has documentation, assume f is simply another
    48  		// implementation and ignore it. This does not happen if the
    49  		// caller is using go/build.ScanDir to determine the list of
    50  		// files implementing a package.
    51  		return
    52  	}
    53  	// function doesn't exist or has no documentation; use f
    54  	recv := ""
    55  	if f.Recv != nil {
    56  		var typ ast.Expr
    57  		// be careful in case of incorrect ASTs
    58  		if list := f.Recv.List; len(list) == 1 {
    59  			typ = list[0].Type
    60  		}
    61  		recv = recvString(typ)
    62  	}
    63  	mset[name] = &Func{
    64  		Doc:  f.Doc.Text(),
    65  		Name: name,
    66  		Decl: f,
    67  		Recv: recv,
    68  		Orig: recv,
    69  	}
    70  	if !preserveAST {
    71  		f.Doc = nil // doc consumed - remove from AST
    72  	}
    73  }
    74  
    75  // add adds method m to the method set; m is ignored if the method set
    76  // already contains a method with the same name at the same or a higher
    77  // level than m.
    78  //
    79  func (mset methodSet) add(m *Func) {
    80  	old := mset[m.Name]
    81  	if old == nil || m.Level < old.Level {
    82  		mset[m.Name] = m
    83  		return
    84  	}
    85  	if m.Level == old.Level {
    86  		// conflict - mark it using a method with nil Decl
    87  		mset[m.Name] = &Func{
    88  			Name:  m.Name,
    89  			Level: m.Level,
    90  		}
    91  	}
    92  }
    93  
    94  // ----------------------------------------------------------------------------
    95  // Named types
    96  
    97  // baseTypeName returns the name of the base type of x (or "")
    98  // and whether the type is imported or not.
    99  //
   100  func baseTypeName(x ast.Expr) (name string, imported bool) {
   101  	switch t := x.(type) {
   102  	case *ast.Ident:
   103  		return t.Name, false
   104  	case *ast.SelectorExpr:
   105  		if _, ok := t.X.(*ast.Ident); ok {
   106  			// only possible for qualified type names;
   107  			// assume type is imported
   108  			return t.Sel.Name, true
   109  		}
   110  	case *ast.ParenExpr:
   111  		return baseTypeName(t.X)
   112  	case *ast.StarExpr:
   113  		return baseTypeName(t.X)
   114  	}
   115  	return
   116  }
   117  
   118  // An embeddedSet describes a set of embedded types.
   119  type embeddedSet map[*namedType]bool
   120  
   121  // A namedType represents a named unqualified (package local, or possibly
   122  // predeclared) type. The namedType for a type name is always found via
   123  // reader.lookupType.
   124  //
   125  type namedType struct {
   126  	doc  string       // doc comment for type
   127  	name string       // type name
   128  	decl *ast.GenDecl // nil if declaration hasn't been seen yet
   129  
   130  	isEmbedded bool        // true if this type is embedded
   131  	isStruct   bool        // true if this type is a struct
   132  	embedded   embeddedSet // true if the embedded type is a pointer
   133  
   134  	// associated declarations
   135  	values  []*Value // consts and vars
   136  	funcs   methodSet
   137  	methods methodSet
   138  }
   139  
   140  // ----------------------------------------------------------------------------
   141  // AST reader
   142  
   143  // reader accumulates documentation for a single package.
   144  // It modifies the AST: Comments (declaration documentation)
   145  // that have been collected by the reader are set to nil
   146  // in the respective AST nodes so that they are not printed
   147  // twice (once when printing the documentation and once when
   148  // printing the corresponding AST node).
   149  //
   150  type reader struct {
   151  	mode Mode
   152  
   153  	// package properties
   154  	doc       string // package documentation, if any
   155  	filenames []string
   156  	notes     map[string][]*Note
   157  
   158  	// declarations
   159  	imports   map[string]int
   160  	hasDotImp bool     // if set, package contains a dot import
   161  	values    []*Value // consts and vars
   162  	order     int      // sort order of const and var declarations (when we can't use a name)
   163  	types     map[string]*namedType
   164  	funcs     methodSet
   165  
   166  	// support for package-local error type declarations
   167  	errorDecl bool                 // if set, type "error" was declared locally
   168  	fixlist   []*ast.InterfaceType // list of interfaces containing anonymous field "error"
   169  }
   170  
   171  func (r *reader) isVisible(name string) bool {
   172  	return r.mode&AllDecls != 0 || token.IsExported(name)
   173  }
   174  
   175  // lookupType returns the base type with the given name.
   176  // If the base type has not been encountered yet, a new
   177  // type with the given name but no associated declaration
   178  // is added to the type map.
   179  //
   180  func (r *reader) lookupType(name string) *namedType {
   181  	if name == "" || name == "_" {
   182  		return nil // no type docs for anonymous types
   183  	}
   184  	if typ, found := r.types[name]; found {
   185  		return typ
   186  	}
   187  	// type not found - add one without declaration
   188  	typ := &namedType{
   189  		name:     name,
   190  		embedded: make(embeddedSet),
   191  		funcs:    make(methodSet),
   192  		methods:  make(methodSet),
   193  	}
   194  	r.types[name] = typ
   195  	return typ
   196  }
   197  
   198  // recordAnonymousField registers fieldType as the type of an
   199  // anonymous field in the parent type. If the field is imported
   200  // (qualified name) or the parent is nil, the field is ignored.
   201  // The function returns the field name.
   202  //
   203  func (r *reader) recordAnonymousField(parent *namedType, fieldType ast.Expr) (fname string) {
   204  	fname, imp := baseTypeName(fieldType)
   205  	if parent == nil || imp {
   206  		return
   207  	}
   208  	if ftype := r.lookupType(fname); ftype != nil {
   209  		ftype.isEmbedded = true
   210  		_, ptr := fieldType.(*ast.StarExpr)
   211  		parent.embedded[ftype] = ptr
   212  	}
   213  	return
   214  }
   215  
   216  func (r *reader) readDoc(comment *ast.CommentGroup) {
   217  	// By convention there should be only one package comment
   218  	// but collect all of them if there are more than one.
   219  	text := comment.Text()
   220  	if r.doc == "" {
   221  		r.doc = text
   222  		return
   223  	}
   224  	r.doc += "\n" + text
   225  }
   226  
   227  func (r *reader) remember(typ *ast.InterfaceType) {
   228  	r.fixlist = append(r.fixlist, typ)
   229  }
   230  
   231  func specNames(specs []ast.Spec) []string {
   232  	names := make([]string, 0, len(specs)) // reasonable estimate
   233  	for _, s := range specs {
   234  		// s guaranteed to be an *ast.ValueSpec by readValue
   235  		for _, ident := range s.(*ast.ValueSpec).Names {
   236  			names = append(names, ident.Name)
   237  		}
   238  	}
   239  	return names
   240  }
   241  
   242  // readValue processes a const or var declaration.
   243  //
   244  func (r *reader) readValue(decl *ast.GenDecl) {
   245  	// determine if decl should be associated with a type
   246  	// Heuristic: For each typed entry, determine the type name, if any.
   247  	//            If there is exactly one type name that is sufficiently
   248  	//            frequent, associate the decl with the respective type.
   249  	domName := ""
   250  	domFreq := 0
   251  	prev := ""
   252  	n := 0
   253  	for _, spec := range decl.Specs {
   254  		s, ok := spec.(*ast.ValueSpec)
   255  		if !ok {
   256  			continue // should not happen, but be conservative
   257  		}
   258  		name := ""
   259  		switch {
   260  		case s.Type != nil:
   261  			// a type is present; determine its name
   262  			if n, imp := baseTypeName(s.Type); !imp {
   263  				name = n
   264  			}
   265  		case decl.Tok == token.CONST && len(s.Values) == 0:
   266  			// no type or value is present but we have a constant declaration;
   267  			// use the previous type name (possibly the empty string)
   268  			name = prev
   269  		}
   270  		if name != "" {
   271  			// entry has a named type
   272  			if domName != "" && domName != name {
   273  				// more than one type name - do not associate
   274  				// with any type
   275  				domName = ""
   276  				break
   277  			}
   278  			domName = name
   279  			domFreq++
   280  		}
   281  		prev = name
   282  		n++
   283  	}
   284  
   285  	// nothing to do w/o a legal declaration
   286  	if n == 0 {
   287  		return
   288  	}
   289  
   290  	// determine values list with which to associate the Value for this decl
   291  	values := &r.values
   292  	const threshold = 0.75
   293  	if domName != "" && r.isVisible(domName) && domFreq >= int(float64(len(decl.Specs))*threshold) {
   294  		// typed entries are sufficiently frequent
   295  		if typ := r.lookupType(domName); typ != nil {
   296  			values = &typ.values // associate with that type
   297  		}
   298  	}
   299  
   300  	*values = append(*values, &Value{
   301  		Doc:   decl.Doc.Text(),
   302  		Names: specNames(decl.Specs),
   303  		Decl:  decl,
   304  		order: r.order,
   305  	})
   306  	if r.mode&PreserveAST == 0 {
   307  		decl.Doc = nil // doc consumed - remove from AST
   308  	}
   309  	// Note: It's important that the order used here is global because the cleanupTypes
   310  	// methods may move values associated with types back into the global list. If the
   311  	// order is list-specific, sorting is not deterministic because the same order value
   312  	// may appear multiple times (was bug, found when fixing #16153).
   313  	r.order++
   314  }
   315  
   316  // fields returns a struct's fields or an interface's methods.
   317  //
   318  func fields(typ ast.Expr) (list []*ast.Field, isStruct bool) {
   319  	var fields *ast.FieldList
   320  	switch t := typ.(type) {
   321  	case *ast.StructType:
   322  		fields = t.Fields
   323  		isStruct = true
   324  	case *ast.InterfaceType:
   325  		fields = t.Methods
   326  	}
   327  	if fields != nil {
   328  		list = fields.List
   329  	}
   330  	return
   331  }
   332  
   333  // readType processes a type declaration.
   334  //
   335  func (r *reader) readType(decl *ast.GenDecl, spec *ast.TypeSpec) {
   336  	typ := r.lookupType(spec.Name.Name)
   337  	if typ == nil {
   338  		return // no name or blank name - ignore the type
   339  	}
   340  
   341  	// A type should be added at most once, so typ.decl
   342  	// should be nil - if it is not, simply overwrite it.
   343  	typ.decl = decl
   344  
   345  	// compute documentation
   346  	doc := spec.Doc
   347  	if doc == nil {
   348  		// no doc associated with the spec, use the declaration doc, if any
   349  		doc = decl.Doc
   350  	}
   351  	if r.mode&PreserveAST == 0 {
   352  		spec.Doc = nil // doc consumed - remove from AST
   353  		decl.Doc = nil // doc consumed - remove from AST
   354  	}
   355  	typ.doc = doc.Text()
   356  
   357  	// record anonymous fields (they may contribute methods)
   358  	// (some fields may have been recorded already when filtering
   359  	// exports, but that's ok)
   360  	var list []*ast.Field
   361  	list, typ.isStruct = fields(spec.Type)
   362  	for _, field := range list {
   363  		if len(field.Names) == 0 {
   364  			r.recordAnonymousField(typ, field.Type)
   365  		}
   366  	}
   367  }
   368  
   369  // isPredeclared reports whether n denotes a predeclared type.
   370  //
   371  func (r *reader) isPredeclared(n string) bool {
   372  	return predeclaredTypes[n] && r.types[n] == nil
   373  }
   374  
   375  // readFunc processes a func or method declaration.
   376  //
   377  func (r *reader) readFunc(fun *ast.FuncDecl) {
   378  	// strip function body if requested.
   379  	if r.mode&PreserveAST == 0 {
   380  		fun.Body = nil
   381  	}
   382  
   383  	// associate methods with the receiver type, if any
   384  	if fun.Recv != nil {
   385  		// method
   386  		if len(fun.Recv.List) == 0 {
   387  			// should not happen (incorrect AST); (See issue 17788)
   388  			// don't show this method
   389  			return
   390  		}
   391  		recvTypeName, imp := baseTypeName(fun.Recv.List[0].Type)
   392  		if imp {
   393  			// should not happen (incorrect AST);
   394  			// don't show this method
   395  			return
   396  		}
   397  		if typ := r.lookupType(recvTypeName); typ != nil {
   398  			typ.methods.set(fun, r.mode&PreserveAST != 0)
   399  		}
   400  		// otherwise ignore the method
   401  		// TODO(gri): There may be exported methods of non-exported types
   402  		// that can be called because of exported values (consts, vars, or
   403  		// function results) of that type. Could determine if that is the
   404  		// case and then show those methods in an appropriate section.
   405  		return
   406  	}
   407  
   408  	// Associate factory functions with the first visible result type, as long as
   409  	// others are predeclared types.
   410  	if fun.Type.Results.NumFields() >= 1 {
   411  		var typ *namedType // type to associate the function with
   412  		numResultTypes := 0
   413  		for _, res := range fun.Type.Results.List {
   414  			factoryType := res.Type
   415  			if t, ok := factoryType.(*ast.ArrayType); ok {
   416  				// We consider functions that return slices or arrays of type
   417  				// T (or pointers to T) as factory functions of T.
   418  				factoryType = t.Elt
   419  			}
   420  			if n, imp := baseTypeName(factoryType); !imp && r.isVisible(n) && !r.isPredeclared(n) {
   421  				if t := r.lookupType(n); t != nil {
   422  					typ = t
   423  					numResultTypes++
   424  					if numResultTypes > 1 {
   425  						break
   426  					}
   427  				}
   428  			}
   429  		}
   430  		// If there is exactly one result type,
   431  		// associate the function with that type.
   432  		if numResultTypes == 1 {
   433  			typ.funcs.set(fun, r.mode&PreserveAST != 0)
   434  			return
   435  		}
   436  	}
   437  
   438  	// just an ordinary function
   439  	r.funcs.set(fun, r.mode&PreserveAST != 0)
   440  }
   441  
   442  var (
   443  	noteMarker    = `([A-Z][A-Z]+)\(([^)]+)\):?`                // MARKER(uid), MARKER at least 2 chars, uid at least 1 char
   444  	noteMarkerRx  = lazyregexp.New(`^[ \t]*` + noteMarker)      // MARKER(uid) at text start
   445  	noteCommentRx = lazyregexp.New(`^/[/*][ \t]*` + noteMarker) // MARKER(uid) at comment start
   446  )
   447  
   448  // readNote collects a single note from a sequence of comments.
   449  //
   450  func (r *reader) readNote(list []*ast.Comment) {
   451  	text := (&ast.CommentGroup{List: list}).Text()
   452  	if m := noteMarkerRx.FindStringSubmatchIndex(text); m != nil {
   453  		// The note body starts after the marker.
   454  		// We remove any formatting so that we don't
   455  		// get spurious line breaks/indentation when
   456  		// showing the TODO body.
   457  		body := clean(text[m[1]:], keepNL)
   458  		if body != "" {
   459  			marker := text[m[2]:m[3]]
   460  			r.notes[marker] = append(r.notes[marker], &Note{
   461  				Pos:  list[0].Pos(),
   462  				End:  list[len(list)-1].End(),
   463  				UID:  text[m[4]:m[5]],
   464  				Body: body,
   465  			})
   466  		}
   467  	}
   468  }
   469  
   470  // readNotes extracts notes from comments.
   471  // A note must start at the beginning of a comment with "MARKER(uid):"
   472  // and is followed by the note body (e.g., "// BUG(gri): fix this").
   473  // The note ends at the end of the comment group or at the start of
   474  // another note in the same comment group, whichever comes first.
   475  //
   476  func (r *reader) readNotes(comments []*ast.CommentGroup) {
   477  	for _, group := range comments {
   478  		i := -1 // comment index of most recent note start, valid if >= 0
   479  		list := group.List
   480  		for j, c := range list {
   481  			if noteCommentRx.MatchString(c.Text) {
   482  				if i >= 0 {
   483  					r.readNote(list[i:j])
   484  				}
   485  				i = j
   486  			}
   487  		}
   488  		if i >= 0 {
   489  			r.readNote(list[i:])
   490  		}
   491  	}
   492  }
   493  
   494  // readFile adds the AST for a source file to the reader.
   495  //
   496  func (r *reader) readFile(src *ast.File) {
   497  	// add package documentation
   498  	if src.Doc != nil {
   499  		r.readDoc(src.Doc)
   500  		if r.mode&PreserveAST == 0 {
   501  			src.Doc = nil // doc consumed - remove from AST
   502  		}
   503  	}
   504  
   505  	// add all declarations but for functions which are processed in a separate pass
   506  	for _, decl := range src.Decls {
   507  		switch d := decl.(type) {
   508  		case *ast.GenDecl:
   509  			switch d.Tok {
   510  			case token.IMPORT:
   511  				// imports are handled individually
   512  				for _, spec := range d.Specs {
   513  					if s, ok := spec.(*ast.ImportSpec); ok {
   514  						if import_, err := strconv.Unquote(s.Path.Value); err == nil {
   515  							r.imports[import_] = 1
   516  							if s.Name != nil && s.Name.Name == "." {
   517  								r.hasDotImp = true
   518  							}
   519  						}
   520  					}
   521  				}
   522  			case token.CONST, token.VAR:
   523  				// constants and variables are always handled as a group
   524  				r.readValue(d)
   525  			case token.TYPE:
   526  				// types are handled individually
   527  				if len(d.Specs) == 1 && !d.Lparen.IsValid() {
   528  					// common case: single declaration w/o parentheses
   529  					// (if a single declaration is parenthesized,
   530  					// create a new fake declaration below, so that
   531  					// go/doc type declarations always appear w/o
   532  					// parentheses)
   533  					if s, ok := d.Specs[0].(*ast.TypeSpec); ok {
   534  						r.readType(d, s)
   535  					}
   536  					break
   537  				}
   538  				for _, spec := range d.Specs {
   539  					if s, ok := spec.(*ast.TypeSpec); ok {
   540  						// use an individual (possibly fake) declaration
   541  						// for each type; this also ensures that each type
   542  						// gets to (re-)use the declaration documentation
   543  						// if there's none associated with the spec itself
   544  						fake := &ast.GenDecl{
   545  							Doc: d.Doc,
   546  							// don't use the existing TokPos because it
   547  							// will lead to the wrong selection range for
   548  							// the fake declaration if there are more
   549  							// than one type in the group (this affects
   550  							// src/cmd/godoc/godoc.go's posLink_urlFunc)
   551  							TokPos: s.Pos(),
   552  							Tok:    token.TYPE,
   553  							Specs:  []ast.Spec{s},
   554  						}
   555  						r.readType(fake, s)
   556  					}
   557  				}
   558  			}
   559  		}
   560  	}
   561  
   562  	// collect MARKER(...): annotations
   563  	r.readNotes(src.Comments)
   564  	if r.mode&PreserveAST == 0 {
   565  		src.Comments = nil // consumed unassociated comments - remove from AST
   566  	}
   567  }
   568  
   569  func (r *reader) readPackage(pkg *ast.Package, mode Mode) {
   570  	// initialize reader
   571  	r.filenames = make([]string, len(pkg.Files))
   572  	r.imports = make(map[string]int)
   573  	r.mode = mode
   574  	r.types = make(map[string]*namedType)
   575  	r.funcs = make(methodSet)
   576  	r.notes = make(map[string][]*Note)
   577  
   578  	// sort package files before reading them so that the
   579  	// result does not depend on map iteration order
   580  	i := 0
   581  	for filename := range pkg.Files {
   582  		r.filenames[i] = filename
   583  		i++
   584  	}
   585  	sort.Strings(r.filenames)
   586  
   587  	// process files in sorted order
   588  	for _, filename := range r.filenames {
   589  		f := pkg.Files[filename]
   590  		if mode&AllDecls == 0 {
   591  			r.fileExports(f)
   592  		}
   593  		r.readFile(f)
   594  	}
   595  
   596  	// process functions now that we have better type information
   597  	for _, f := range pkg.Files {
   598  		for _, decl := range f.Decls {
   599  			if d, ok := decl.(*ast.FuncDecl); ok {
   600  				r.readFunc(d)
   601  			}
   602  		}
   603  	}
   604  }
   605  
   606  // ----------------------------------------------------------------------------
   607  // Types
   608  
   609  func customizeRecv(f *Func, recvTypeName string, embeddedIsPtr bool, level int) *Func {
   610  	if f == nil || f.Decl == nil || f.Decl.Recv == nil || len(f.Decl.Recv.List) != 1 {
   611  		return f // shouldn't happen, but be safe
   612  	}
   613  
   614  	// copy existing receiver field and set new type
   615  	newField := *f.Decl.Recv.List[0]
   616  	origPos := newField.Type.Pos()
   617  	_, origRecvIsPtr := newField.Type.(*ast.StarExpr)
   618  	newIdent := &ast.Ident{NamePos: origPos, Name: recvTypeName}
   619  	var typ ast.Expr = newIdent
   620  	if !embeddedIsPtr && origRecvIsPtr {
   621  		newIdent.NamePos++ // '*' is one character
   622  		typ = &ast.StarExpr{Star: origPos, X: newIdent}
   623  	}
   624  	newField.Type = typ
   625  
   626  	// copy existing receiver field list and set new receiver field
   627  	newFieldList := *f.Decl.Recv
   628  	newFieldList.List = []*ast.Field{&newField}
   629  
   630  	// copy existing function declaration and set new receiver field list
   631  	newFuncDecl := *f.Decl
   632  	newFuncDecl.Recv = &newFieldList
   633  
   634  	// copy existing function documentation and set new declaration
   635  	newF := *f
   636  	newF.Decl = &newFuncDecl
   637  	newF.Recv = recvString(typ)
   638  	// the Orig field never changes
   639  	newF.Level = level
   640  
   641  	return &newF
   642  }
   643  
   644  // collectEmbeddedMethods collects the embedded methods of typ in mset.
   645  //
   646  func (r *reader) collectEmbeddedMethods(mset methodSet, typ *namedType, recvTypeName string, embeddedIsPtr bool, level int, visited embeddedSet) {
   647  	visited[typ] = true
   648  	for embedded, isPtr := range typ.embedded {
   649  		// Once an embedded type is embedded as a pointer type
   650  		// all embedded types in those types are treated like
   651  		// pointer types for the purpose of the receiver type
   652  		// computation; i.e., embeddedIsPtr is sticky for this
   653  		// embedding hierarchy.
   654  		thisEmbeddedIsPtr := embeddedIsPtr || isPtr
   655  		for _, m := range embedded.methods {
   656  			// only top-level methods are embedded
   657  			if m.Level == 0 {
   658  				mset.add(customizeRecv(m, recvTypeName, thisEmbeddedIsPtr, level))
   659  			}
   660  		}
   661  		if !visited[embedded] {
   662  			r.collectEmbeddedMethods(mset, embedded, recvTypeName, thisEmbeddedIsPtr, level+1, visited)
   663  		}
   664  	}
   665  	delete(visited, typ)
   666  }
   667  
   668  // computeMethodSets determines the actual method sets for each type encountered.
   669  //
   670  func (r *reader) computeMethodSets() {
   671  	for _, t := range r.types {
   672  		// collect embedded methods for t
   673  		if t.isStruct {
   674  			// struct
   675  			r.collectEmbeddedMethods(t.methods, t, t.name, false, 1, make(embeddedSet))
   676  		} else {
   677  			// interface
   678  			// TODO(gri) fix this
   679  		}
   680  	}
   681  
   682  	// if error was declared locally, don't treat it as exported field anymore
   683  	if r.errorDecl {
   684  		for _, ityp := range r.fixlist {
   685  			removeErrorField(ityp)
   686  		}
   687  	}
   688  }
   689  
   690  // cleanupTypes removes the association of functions and methods with
   691  // types that have no declaration. Instead, these functions and methods
   692  // are shown at the package level. It also removes types with missing
   693  // declarations or which are not visible.
   694  //
   695  func (r *reader) cleanupTypes() {
   696  	for _, t := range r.types {
   697  		visible := r.isVisible(t.name)
   698  		predeclared := predeclaredTypes[t.name]
   699  
   700  		if t.decl == nil && (predeclared || visible && (t.isEmbedded || r.hasDotImp)) {
   701  			// t.name is a predeclared type (and was not redeclared in this package),
   702  			// or it was embedded somewhere but its declaration is missing (because
   703  			// the AST is incomplete), or we have a dot-import (and all bets are off):
   704  			// move any associated values, funcs, and methods back to the top-level so
   705  			// that they are not lost.
   706  			// 1) move values
   707  			r.values = append(r.values, t.values...)
   708  			// 2) move factory functions
   709  			for name, f := range t.funcs {
   710  				// in a correct AST, package-level function names
   711  				// are all different - no need to check for conflicts
   712  				r.funcs[name] = f
   713  			}
   714  			// 3) move methods
   715  			if !predeclared {
   716  				for name, m := range t.methods {
   717  					// don't overwrite functions with the same name - drop them
   718  					if _, found := r.funcs[name]; !found {
   719  						r.funcs[name] = m
   720  					}
   721  				}
   722  			}
   723  		}
   724  		// remove types w/o declaration or which are not visible
   725  		if t.decl == nil || !visible {
   726  			delete(r.types, t.name)
   727  		}
   728  	}
   729  }
   730  
   731  // ----------------------------------------------------------------------------
   732  // Sorting
   733  
   734  type data struct {
   735  	n    int
   736  	swap func(i, j int)
   737  	less func(i, j int) bool
   738  }
   739  
   740  func (d *data) Len() int           { return d.n }
   741  func (d *data) Swap(i, j int)      { d.swap(i, j) }
   742  func (d *data) Less(i, j int) bool { return d.less(i, j) }
   743  
   744  // sortBy is a helper function for sorting
   745  func sortBy(less func(i, j int) bool, swap func(i, j int), n int) {
   746  	sort.Sort(&data{n, swap, less})
   747  }
   748  
   749  func sortedKeys(m map[string]int) []string {
   750  	list := make([]string, len(m))
   751  	i := 0
   752  	for key := range m {
   753  		list[i] = key
   754  		i++
   755  	}
   756  	sort.Strings(list)
   757  	return list
   758  }
   759  
   760  // sortingName returns the name to use when sorting d into place.
   761  //
   762  func sortingName(d *ast.GenDecl) string {
   763  	if len(d.Specs) == 1 {
   764  		if s, ok := d.Specs[0].(*ast.ValueSpec); ok {
   765  			return s.Names[0].Name
   766  		}
   767  	}
   768  	return ""
   769  }
   770  
   771  func sortedValues(m []*Value, tok token.Token) []*Value {
   772  	list := make([]*Value, len(m)) // big enough in any case
   773  	i := 0
   774  	for _, val := range m {
   775  		if val.Decl.Tok == tok {
   776  			list[i] = val
   777  			i++
   778  		}
   779  	}
   780  	list = list[0:i]
   781  
   782  	sortBy(
   783  		func(i, j int) bool {
   784  			if ni, nj := sortingName(list[i].Decl), sortingName(list[j].Decl); ni != nj {
   785  				return ni < nj
   786  			}
   787  			return list[i].order < list[j].order
   788  		},
   789  		func(i, j int) { list[i], list[j] = list[j], list[i] },
   790  		len(list),
   791  	)
   792  
   793  	return list
   794  }
   795  
   796  func sortedTypes(m map[string]*namedType, allMethods bool) []*Type {
   797  	list := make([]*Type, len(m))
   798  	i := 0
   799  	for _, t := range m {
   800  		list[i] = &Type{
   801  			Doc:     t.doc,
   802  			Name:    t.name,
   803  			Decl:    t.decl,
   804  			Consts:  sortedValues(t.values, token.CONST),
   805  			Vars:    sortedValues(t.values, token.VAR),
   806  			Funcs:   sortedFuncs(t.funcs, true),
   807  			Methods: sortedFuncs(t.methods, allMethods),
   808  		}
   809  		i++
   810  	}
   811  
   812  	sortBy(
   813  		func(i, j int) bool { return list[i].Name < list[j].Name },
   814  		func(i, j int) { list[i], list[j] = list[j], list[i] },
   815  		len(list),
   816  	)
   817  
   818  	return list
   819  }
   820  
   821  func removeStar(s string) string {
   822  	if len(s) > 0 && s[0] == '*' {
   823  		return s[1:]
   824  	}
   825  	return s
   826  }
   827  
   828  func sortedFuncs(m methodSet, allMethods bool) []*Func {
   829  	list := make([]*Func, len(m))
   830  	i := 0
   831  	for _, m := range m {
   832  		// determine which methods to include
   833  		switch {
   834  		case m.Decl == nil:
   835  			// exclude conflict entry
   836  		case allMethods, m.Level == 0, !token.IsExported(removeStar(m.Orig)):
   837  			// forced inclusion, method not embedded, or method
   838  			// embedded but original receiver type not exported
   839  			list[i] = m
   840  			i++
   841  		}
   842  	}
   843  	list = list[0:i]
   844  	sortBy(
   845  		func(i, j int) bool { return list[i].Name < list[j].Name },
   846  		func(i, j int) { list[i], list[j] = list[j], list[i] },
   847  		len(list),
   848  	)
   849  	return list
   850  }
   851  
   852  // noteBodies returns a list of note body strings given a list of notes.
   853  // This is only used to populate the deprecated Package.Bugs field.
   854  //
   855  func noteBodies(notes []*Note) []string {
   856  	var list []string
   857  	for _, n := range notes {
   858  		list = append(list, n.Body)
   859  	}
   860  	return list
   861  }
   862  
   863  // ----------------------------------------------------------------------------
   864  // Predeclared identifiers
   865  
   866  // IsPredeclared reports whether s is a predeclared identifier.
   867  func IsPredeclared(s string) bool {
   868  	return predeclaredTypes[s] || predeclaredFuncs[s] || predeclaredConstants[s]
   869  }
   870  
   871  var predeclaredTypes = map[string]bool{
   872  	"bool":       true,
   873  	"byte":       true,
   874  	"complex64":  true,
   875  	"complex128": true,
   876  	"error":      true,
   877  	"float32":    true,
   878  	"float64":    true,
   879  	"int":        true,
   880  	"int8":       true,
   881  	"int16":      true,
   882  	"int32":      true,
   883  	"int64":      true,
   884  	"rune":       true,
   885  	"string":     true,
   886  	"uint":       true,
   887  	"uint8":      true,
   888  	"uint16":     true,
   889  	"uint32":     true,
   890  	"uint64":     true,
   891  	"uintptr":    true,
   892  }
   893  
   894  var predeclaredFuncs = map[string]bool{
   895  	"append":  true,
   896  	"cap":     true,
   897  	"close":   true,
   898  	"complex": true,
   899  	"copy":    true,
   900  	"delete":  true,
   901  	"imag":    true,
   902  	"len":     true,
   903  	"make":    true,
   904  	"new":     true,
   905  	"panic":   true,
   906  	"print":   true,
   907  	"println": true,
   908  	"real":    true,
   909  	"recover": true,
   910  }
   911  
   912  var predeclaredConstants = map[string]bool{
   913  	"false": true,
   914  	"iota":  true,
   915  	"nil":   true,
   916  	"true":  true,
   917  }
   918  

View as plain text