x/pkgsite: Organization of package-level constants

[tooolbox]

What did you do?

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

What did you expect to see?

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

What did you see instead?

No constants!

Instead, the constants are grouped under their types:

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

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.

[tooolbox]

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]

/cc @julieqiu @jba @jamalc