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

cmd/doc: should not print long slices in general summary #13072

Closed
dsnet opened this issue Oct 27, 2015 · 3 comments
Closed

cmd/doc: should not print long slices in general summary #13072

dsnet opened this issue Oct 27, 2015 · 3 comments
Labels
FrozenDueToAge
Milestone
Unplanned

Comments

@dsnet
Copy link
Member

dsnet commented Oct 27, 2015

Using go1.5

Use go doc image/color/palette:

package palette // import "image/color/palette"

Package palette provides standard color palettes.

var Plan9 = []color.Color{
    color.RGBA{0x00, 0x00, 0x00, 0xff},
    color.RGBA{0x00, 0x00, 0x44, 0xff},
    color.RGBA{0x00, 0x00, 0x88, 0xff},
    ...
    color.RGBA{0xff, 0xff, 0x55, 0xff},
    color.RGBA{0xff, 0xff, 0xaa, 0xff},
    color.RGBA{0xff, 0xff, 0xff, 0xff},
}
var WebSafe = []color.Color{
    color.RGBA{0x00, 0x00, 0x00, 0xff},
    color.RGBA{0x00, 0x00, 0x33, 0xff},
    color.RGBA{0x00, 0x00, 0x66, 0xff},
    ...
    color.RGBA{0xff, 0xff, 0x99, 0xff},
    color.RGBA{0xff, 0xff, 0xcc, 0xff},
    color.RGBA{0xff, 0xff, 0xff, 0xff},
}

Note that the "..." above is me inserting them, not what the tool prints. Otherwise, this issue would be ridiculously long.

I expect to see:

package palette // import "image/color/palette"

Package palette provides standard color palettes.

var Plan9 = []color.Color{ ... }
var WebSafe = []color.Color{ ... }

The fact that it prints the entire slice is annoying especially since I'm working on a package that contains a huge look-up table with 100k elements. Printing that out makes the tool unusable.
@ianlancetaylor ianlancetaylor added this to the Unplanned milestone Oct 28, 2015
@rakyll
Copy link
Contributor

rakyll commented Oct 28, 2015

Could you give a bit more rationale why you think printing out the slice makes the tool unusable? The package only exports those slices, and the users are likely willing to see the exported values.

If you have a huge look-up table and want better docs, maybe you need to reorganize your package.

@dsnet
Copy link
Member Author

dsnet commented Oct 28, 2015

Sure, it seems the tool collapses categories with many items together to reduce the noise at the top level. So, if we do go doc syscall, it collapses the long list of constants to be a single one-line entry const AF_ALG = 0x26 .... If a person wanted to know more about all the constants in that block, they can simply do go doc syscall AF_ALG and then it will proceed to print all the constants. I think what the doc tool does for constants and variable block is great. This issue that I've filed is about extending that philosophy to slices as well.

I mentioned image/color/palette as an example of a library where printing all the contents is not necessary. Someone doing go doc image/color/palette probably only cares about what palettes exist and not what the values of the palette are. If they do care about the actual values, they can be more specific and ask for go doc image/color/palette Plan9.

Another practical example (and this was my original motivation for this change) was using go doc -u in a package I'm working on to keep track of the different private methods that exist. The package I'm working on has quite a large number of look-up tables, and it's really distracting needing to ignore all of the LUTs in order to get to private methods I care about. Even within the standard library, you can see noisiness by doing go doc -u compress/flate and it used to be worse before a large LUT was removed.

Furthermore, this is more in line with what the help for the doc tool says (emphasis mine):

Doc prints the documentation comments associated with the item identified by its
arguments (a package, const, func, type, var, or method) followed by a one-line
summary of each of the first-level items "under" that item (package-level
declarations for a package, methods for a type, etc.).

@gopherbot
Copy link

CL https://golang.org/cl/25420 mentions this issue.

@golang golang locked and limited conversation to collaborators Oct 5, 2017
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
FrozenDueToAge
Projects
None yet
Milestone
Unplanned
Development

No branches or pull requests
4 participants
@rakyll @ianlancetaylor @dsnet @gopherbot