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

x/pkgsite: Organization of package-level constants #40970

Open
tooolbox opened this issue Aug 21, 2020 · 2 comments
Open

x/pkgsite: Organization of package-level constants #40970

tooolbox opened this issue Aug 21, 2020 · 2 comments

Comments

@tooolbox
Copy link

@tooolbox tooolbox commented Aug 21, 2020

What did you do?

Visited https://pkg.go.dev/cuelang.org/go/cue?tab=doc

Screen Shot 2020-08-21 at 2 50 32 PM

What did you expect to see?

Below the Index (and Package Files) I expected to see all of the constants available in the package.

Screen Shot 2020-08-21 at 2 51 12 PM

What did you see instead?

No constants!

Instead, the constants are grouped under their types:

Screen Shot 2020-08-21 at 2 52 20 PM

This is not always the case, for example in Logrus:

Screen Shot 2020-08-21 at 2 55 21 PM

The difference may be that, because those package-level constants are strings, they have no type to be grouped under and so float to the top. Also, there are some package-level variables that are still at the top—so maybe those are treated differently, or maybe it's because it's a slice of that custom type and the logic doesn't take slices into account.

Notes/Feedback

  • I did some searching in the issues and didn't see anything about this point, so please let me know if I'm making a duplicate issue and I'll close in favor.
  • My initial reaction is that this change is subtle and surprising. Godoc has always had the package-level constants and variables at the top, below the Index and before the detailed listing of all of the types, and you can reliably find all this information in one place.
  • Regardless of what I'm personally used to, there's the question of whether or not this is better. Let's break it down a little:
    • Grouping constants with their type would seem to have some amount of benefit because the related data is all in one spot (plus).
    • There is now no single overview of all package-level constants and variables, akin to what the Index provided for types (minus).

I could slice the points more finely and articulate them in various ways, but I believe that the original style of overview was better. You could see all types and methods in the Index, (including constructors) and then below that all of the package-level variables—voila, you have seen the package's public API. If you have questions about the type of these constants, you can click them to drill down to the details. Colocating the constants with their types seems to "ease" this click step by sacrificing the overview.

Perhaps, as an alternative, if a type has constants, it can have a link to the Constants section up top?

This is my impression as a user, but I'm curious what other community members think.

@gopherbot gopherbot added this to the Unreleased milestone Aug 21, 2020
@tooolbox
Copy link
Author

@tooolbox tooolbox commented Aug 21, 2020

Hm, now I'm a little confused.

Here's the PayPal REST API in Godoc: https://godoc.org/github.com/plutov/paypal

Most of the constants are up top, but UserAction has its constants grouped under the type. The pkg.go.dev version is definitely different, with more constants grouped under their types, but clearly it's not black-and-white and I can't tell why.

@cagedmantis
Copy link
Contributor

@cagedmantis cagedmantis commented Aug 24, 2020

@gopherbot gopherbot added the go.dev label Sep 18, 2020
@julieqiu julieqiu removed the go.dev label Sep 19, 2020
@gopherbot gopherbot added the go.dev label Sep 19, 2020
@julieqiu julieqiu removed the go.dev label Sep 19, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
5 participants
You can’t perform that action at this time.