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

tooolbox opened this issue Aug 21, 2020 · 2 comments

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

tooolbox opened this issue Aug 21, 2020 · 2 comments
NeedsInvestigation pkgsite/dochtml pkgsite


Copy link

@tooolbox tooolbox commented Aug 21, 2020

What did you do?


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.


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

@tooolbox tooolbox commented Aug 21, 2020

Hm, now I'm a little confused.

Here's the PayPal REST API in Godoc:

Most of the constants are up top, but UserAction has its constants grouped under the type. The 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 cagedmantis added pkgsite NeedsInvestigation labels Aug 24, 2020
Copy link

@cagedmantis cagedmantis commented Aug 24, 2020

/cc @julieqiu @jba @jamalc

@jba jba removed this from the Unreleased milestone Aug 24, 2020
@jba jba added this to the pkgsite/ milestone Aug 24, 2020
@julieqiu julieqiu removed the website label Sep 19, 2020
@julieqiu julieqiu removed the website label Sep 19, 2020
@julieqiu julieqiu removed this from the pkgsite/ milestone Dec 2, 2020
@julieqiu julieqiu added this to the pkgsite/dochtml milestone Dec 2, 2020
@hyangah hyangah added the pkgsite/dochtml label May 20, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
NeedsInvestigation pkgsite/dochtml pkgsite
None yet

No branches or pull requests

6 participants