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