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/tools/cmd/godoc: don't show internal values #30370
Comments
In some cases you do want to show that information. If you hide it, then it provides no way for that information to be intentionally shown. In some cases you don't want to show that information, in which case the workaround is as straight forward: #11758 (comment). Either policy results is not ideal for one use-case or the other. However, the current policy is more flexible, so seems like the better choice. |
It is true that it is straight forward, but the solution suggested by Russ will still show something that, IMHO, is not useful for people who read the documentation, and may show some internal details. The variable documentation in the package https://godoc.org/golang.org/x/text/encoding/charmap is an example. Godoc, shows: var CodePage037 *Charmap = &codePage037 that just add noise. What about a custom convention to make godoc hide the initialization? var X = _x Thanks. |
We already have a lot of conventions like BUG and DEPRECATED. I personally would like to keep godoc minimal and clean. In general, adding |
Keeping godoc simple is a good reason. But I still don't like the fact that one should modify the code to make a tool do the right thing, as with https://github.com/googleapis/google-cloud-go/blob/master/firestore/options.go#L34. But probably this is a very rare case. Thanks |
With something like semi-auto-generated documentation which is consumed by humans, it's not always clear what "the right thing" is. As mentioned earlier, there are cases where you do want the unexported initializers to be shown and some cases where you don't. In your suggested convention, how would users who do want the unexported initializer to be shown achieve that?
I'm not sure I agree that is a better documented. It doesn't tell me the type of X at all.
The solution by Russ is one of many. If you want absolutely nothing shown, you could do: var ExportedGlobal MyType
func init() {
ExportedGlobal = ... // hidden variable initialization logic
} |
Note that the case in #11758 is somewhat different: in that example, the initializer itself doesn't include any explicit unexported identifiers (or even function calls), so it's less obvious that the initializer is not useful to external users. |
What are some examples where you intentionally want to show explicit unexported identifiers in public documentation? Also note that we have an existing mechanism for explicitly showing unexported parts of an API: the |
Here are some real examples (names mangled for obvious reasons): var MaxSize = 1024 * 1024 * envUint64("MAX_LOG_MB")
var MaxTimeout = Duration(100*milliseconds)
var GlobalCache = &Cache{maxSize: 64*1024*1024} |
Ok, that one is kinda neat. But how is the user supposed to know what So that's arguably clearer using an explicit comment, or using only exported functions: // MaxSize is the maximum size, in bytes, of a log file.
//
// If the MAX_LOG_MB environment variable is a valid integer,
// MaxSize is initialized from it;
// otherwise, MaxSize is initialized to to DefaultMaxSize.
var MaxSize or var MaxSize = 1024 * 1024 * env.Uint64("MAX_LOG_MB") (where the user can then follow a link to view the documentation for
Why would the user prefer that over an exported standard-library type with proper documentation? var MaxTimeout = 100 * time.Millisecond
If var GlobalCache = NewSIzedCache(64 * 1024 * 1024) or var GlobalCache = &Cache{MaxSize: 64 * 1024 * 1024} If it isn't user-configurable, why does the user care about its configuration? There isn't anything they can do to change it anyway. |
I'm not sure if this is a duplicate of #11758.
I have noted a workaround in the Go Firestore client implementation to avoid Godoc showing the interval value:
https://github.com/googleapis/google-cloud-go/blob/master/firestore/options.go#L34
I think this is undesiderable. I have noted the problem with other package documentations, e.g. https://godoc.org/golang.org/x/text/encoding/charmap.
Isn't it better if Godoc don't show interval values of global variables?
Thanks.
The text was updated successfully, but these errors were encountered: