Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Open
mdlayher opened this issue Jan 30, 2017 · 2 comments
Open

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

mdlayher opened this issue Jan 30, 2017 · 2 comments
Milestone
Unplanned

Comments

@mdlayher
Copy link
Member

Suggested by @griesemer in another proposal: #18616 (comment).

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: #18616
@mdlayher mdlayher mentioned this issue Jan 30, 2017
Closed
@jimmyfrasche
Copy link
Member

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
Copy link
Contributor

@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).

@jimmyfrasche jimmyfrasche mentioned this issue Mar 19, 2017
Closed
@bradfitz bradfitz added this to the Unplanned milestone Mar 21, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
Unplanned
Development

No branches or pull requests
4 participants
@bradfitz @jimmyfrasche @mdlayher @griesemer