go/types: NewParam/NewField doc missing

[willfaught]

It's unclear what the package param is for, or if it's required (it seems it isn't, from my testing, if all you're doing is calling String() on the constructed types), or that the name must not be empty for anonymous fields.

It would be helpful to point out in the NewField doc that, for anonymous fields, you can get the name to use from the type argument, where that type is either a Named, Basic, or Pointer.

---

Consider this also a request to document all undocumented, exported declarations in go/types:

• Universe
• Unsafe
• (...) String() string
• (...) Underlying() Type
• func (obj *Builtin) Exported() bool
• func (obj *Builtin) Id() string
• func (obj *Builtin) Name() string
• func (obj *Builtin) Parent() *Scope
• func (obj *Builtin) Pkg() *Package
• func (obj *Builtin) Pos() token.Pos
• func (obj *Builtin) Type() Type
• func (obj *Const) Exported() bool
• func (obj *Const) Id() string
• func (obj *Const) Name() string
• func (obj *Const) Parent() *Scope
• func (obj *Const) Pkg() *Package
• func (obj *Const) Pos() token.Pos
• func (obj *Const) Type() Type
• func (obj *Const) Val() constant.Value
• func NewFunc(pos token.Pos, pkg *Package, name string, sig *Signature) *Func
• func (obj *Func) Exported() bool
• func (obj *Func) Id() string
• func (obj *Func) Name() string
• func (obj *Func) Parent() *Scope
• func (obj *Func) Pkg() *Package
• func (obj *Func) Pos() token.Pos
• func (obj *Func) Scope() *Scope
• func (obj *Func) Type() Type
• func NewLabel(pos token.Pos, pkg *Package, name string) *Label
• func (obj *Label) Exported() bool
• func (obj *Label) Id() string
• func (obj *Label) Name() string
• func (obj *Label) Parent() *Scope
• func (obj *Label) Pkg() *Package
• func (obj *Label) Pos() token.Pos
• func (obj *Label) Type() Type
• func (obj *Nil) Exported() bool
• func (obj *Nil) Id() string
• func (obj *Nil) Name() string
• func (obj *Nil) Parent() *Scope
• func (obj *Nil) Pkg() *Package
• func (obj *Nil) Pos() token.Pos
• func (obj *PkgName) Exported() bool
• func (obj *PkgName) Id() string
• func (obj *PkgName) Parent() *Scope
• func (obj *PkgName) Pkg() *Package
• func (obj *PkgName) Pos() token.Pos
• func (obj *PkgName) Type() Type
• func (s *Scope) End() token.Pos
• func (s *StdSizes) Alignof(T Type) int64
• func (s *StdSizes) Offsetsof(fields []*Var) []int64
• func (s *StdSizes) Sizeof(T Type) int64
• func (obj *TypeName) Exported() bool
• func (obj *TypeName) Id() string
• func (obj *TypeName) Name() string
• func (obj *TypeName) Parent() *Scope
• func (obj *TypeName) Pkg() *Package
• func (obj *TypeName) Pos() token.Pos
• func (obj *TypeName) Type() Type
• func NewField(pos token.Pos, pkg *Package, name string, typ Type, anonymous bool) *Var
• func NewParam(pos token.Pos, pkg *Package, name string, typ Type) *Var
• func NewVar(pos token.Pos, pkg *Package, name string, typ Type) *Var
• func (obj *Var) Anonymous() bool
• func (obj *Var) Exported() bool
• func (obj *Var) Id() string
• func (obj *Var) IsField() bool
• func (obj *Var) Name() string
• func (obj *Var) Parent() *Scope
• func (obj *Var) Pkg() *Package
• func (obj *Var) Pos() token.Pos
• func (obj *Var) Type() Type

[mvdan]

/cc @alandonovan @griesemer

[gopherbot]

Change https://golang.org/cl/110975 mentions this issue: go/types: add doc strings to various undocumented exported objects

[willfaught]

Thank you!