proposal: cmd/godoc: treat function returning slice as constructor

[mvdan]

This is sort of a follow-up to #14004. Sometimes, there are constructors that return a slice of a type. For example:

https://golang.org/pkg/net/mail/#pkg-index

func ParseAddressList(list string) ([]*Address, error)
type Address
    func ParseAddress(address string) (*Address, error)
    func (a *Address) String() string

go/doc does not consider ParseAddressList an Address type func as it returns a slice, not the type directly. Since this rule is reserved for the first returned type, I suggest this is relaxed to also allow slices (and perhaps arrays too? but couldn't find an example of that).

CC @aclements @robpike

[dsnet]

Before considering whether the go doc command-line tool should do this, I think we should first discuss of whether the godoc webserver should do this. The link you provided seems to indicate that godoc currently doesn't do this.

There may be strange edge-cases, but grouping slices and arrays of a given type seems reasonable to me.

[mvdan]

Right - even after a few years I still get confused between go doc and godoc. I did indeed mean godoc.

Before considering whether the go doc command-line tool should do this, I think we should first discuss of whether the godoc webserver should do this.

Out of curiosity, why is that? I would assume the logic behind the two - at least the logic concerning constructor funcs - would be the same.

[dsnet]

Out of curiosity, why is that? I would assume the logic behind the two - at least the logic concerning constructor funcs - would be the same.

As of late, the behavior of go doc has been to follow whatever godoc does. It's reasonable to assume that they would be the same. It's just that the change has to happen on one of them first.

[minux]

we need to consider how far do we want to get into reordering. e.g. what about []struct{T}, []struct{T;U}, [][]T, []*T, [][]*T, []*[]T, map[string]T, ... and the list goes on and on.

[mvdan]

we need to consider how far do we want to get into reordering.

This proposal is limited to just slices whose element types are already grouped as constructors. So if funcs that return Foo and *Foo are grouped, those that return []Foo and []*Foo should be too.

[mvdan]

Not sure why I didn't make this a proposal from the start; made it one.

[rsc]

/cc @griesemer

[rsc]

These would be the "new" constructors in the standard library:

go1.txt:pkg crypto/x509, func ParseCertificates([]uint8) ([]*Certificate, error)
go1.txt:pkg go/doc, func Examples(...*ast.File) []*Example
go1.txt:pkg net, func LookupMX(string) ([]*MX, error)
go1.1.txt:pkg net, func LookupNS(string) ([]*NS, error)
go1.1.txt:pkg net/mail, func ParseAddressList(string) ([]*Address, error)
go1.txt:pkg runtime/pprof, func Profiles() []*Profile

At least four of these look like actual constructors. LookupMX and LookupNS are arguably not. (Of course, user.LookupId is considered a constructor for *user.User, so capturing those would be consistent at least.)

(There are a bunch of methods returning slices of things in the same package too, but methods are never "constructors".)

It does seem like it's probably reasonable.

[rsc]

accepting for @golang/proposal-review. If anyone is interested to work on this, a CL would be welcome.

[mvdan]

Happy to work on a patch for 1.10.

[mvdan]

@rsc by the way, why was the title changed to remove x/tools/ from x/tools/cmd/godoc? Is that abbreviation normal for proposal issues, or does this mean that the patch should land in go doc first?

[tomwans]

Hey @mvdan are you still working on this? I was inspired by the recent contribution workshop blog post (https://blog.golang.org/contributor-workshop) and went hunting for bugs. I have a change working locally, would you mind if I submitted a CL?

[mvdan]

@tomwans nope, I was going to get to this after the holidays. Go ahead.

[gopherbot]

Change https://golang.org/cl/54971 mentions this issue: go/doc: classify function returning slice/array as constructor