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.