go/ast: InterfaceType.Methods comment is incomplete

[willfaught]

What did you do?

$ go doc go/ast InterfaceType.Methods

What did you expect to see?

It doesn't explain what type to expect in Methods.List[x].Type, or that Methods.List[x].Names can be empty (for embedded interfaces).

What did you see instead?

type InterfaceType struct {
    Methods *FieldList  // list of methods

    // ... other fields elided ...
}

System details

go version go1.9.1 darwin/amd64
GOARCH="amd64"
GOBIN=""
GOEXE=""
GOHOSTARCH="amd64"
GOHOSTOS="darwin"
GOOS="darwin"
GOPATH="/Users/willfaught/Developer/go"
GORACE=""
GOROOT="/usr/local/Cellar/go/1.9.1/libexec"
GOTOOLDIR="/usr/local/Cellar/go/1.9.1/libexec/pkg/tool/darwin_amd64"
GCCGO="gccgo"
CC="clang"
GOGCCFLAGS="-fPIC -m64 -pthread -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -fdebug-prefix-map=/var/folders/_1/ggvd2t1x7hz_185crsb36zlr0000gp/T/go-build074149053=/tmp/go-build -gno-record-gcc-switches -fno-common"
CXX="clang++"
CGO_ENABLED="1"
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"
GOROOT/bin/go version: go version go1.9.1 darwin/amd64
GOROOT/bin/go tool compile -V: compile version go1.9.1
uname -v: Darwin Kernel Version 16.7.0: Thu Jun 15 17:36:27 PDT 2017; root:xnu-3789.70.16~2/RELEASE_X86_64
ProductName:	Mac OS X
ProductVersion:	10.12.6
BuildVersion:	16G29
lldb --version: lldb-900.0.50.1
  Swift-4.0

[griesemer]

An ast.FieldList element is of type ast.Field which explains that a type can be a method type (the obvious case here). It also explains that Names can be nil for anonymous fields (which is the equivalent of embedded types.

The go/ast documentation is deliberately sparse so that the "forest" (the overall ast package) can be seen despite all the "trees". It's not meant as a tutorial.

What do you suggest?

[willfaught]

Shoot, I missed those Field comments! You're absolutely right. It's clear enough. Thanks for pointing that out. Sorry.