go/doc: enable grouping of functions with common names and suffix N

[mdlayher]

Suggested by @griesemer in another proposal: https://github.com/golang/go/issues/18616#issuecomment-275761203.

An example of the proposed before and after output, for a series of functions called TrailingZeros with integer sizes "N" as a suffix:

Before:

// TrailingZeros16 returns the number of trailing zero bits in x.
// The result is 16 if x == 0.
func TrailingZeros16(x uint16) uint

// TrailingZeros32 returns the number of trailing zero bits in x.
// The result is 32 if x == 0.
func TrailingZeros32(x uint32) uint

// TrailingZeros64 returns the number of trailing zero bits in x.
// The result is 64 if x == 0.
func TrailingZeros64(x uint64) uint

After:

// TrailingZerosN returns the number of trailing zero bits in a uintN value x for N = 16, 32, 64.
// The result is N if x == 0.
func TrailingZeros16(x uint16) uint
func TrailingZeros32(x uint32) uint
func TrailingZeros64(x uint64) uint

Seems like a big usability improvement, and would be useful in at least sync/atomic as it exists now in the stdlib: https://golang.org/pkg/sync/atomic/. Would also be useful for some of the proposed APIs for a math/bits as discussed here: https://github.com/golang/go/issues/18616

[jimmyfrasche]

My questions/concerns are:

• would have to modify golint and tools like that in addition to godoc/go doc/gddo
• how to model it in the go/doc package?
• Seems like it only benefits a small number of packages
• Where to draw the line? Does it work for types, vars, consts? Can the suffix be the empty string (to group patterns like X, XString)? What about shared prefixes? What if the declarations are in different files? What if they're methods attached to different types?

(as for modelling in go/doc the simplest way would just be to copy the doc string into each Func, but it would be hard to discover the grouping and the decl containing the actual comment without an additional field or method for retrieving the decl with the comment)

I'm not opposed to this change, and I could see it being a benefit, but I'm not convinced it justifies its complexity yet.

[griesemer]

@jimmyfrasche Some (possible) answers:

• The go/doc model could expose an additional field per function/method that ties those together that are part of a "group". The additional field would be the *Group.
• Whether it is beneficial enough is to been seen. May still be worthwhile.
• Types, vars and consts can be grouped already (n the langugae). Go/doc already has some heuristics about which comment to choose (group comment vs individual comment).