theme: hide "useless" tags and methods, such as JSON marshaling

[buchanae]

I have a package with lot of types, and few methods: https://godoc.org/github.com/buchanae/cwl

This package represents a document type, named CWL, so the types are the meat of the package. Unfortunately, due to the way JSON marshaling works, there is a lot of extra stuff which is not that interesting – "json" tags (almost always the same) and MarshalJSON or MarshalText methods.

What would you think about having an option to hide these details which I, as a package author, deem "less than useful"?

[dmitshur]

I personally think it's a good idea to use existing tools that Go 1 provides to hide or deemphasize "less than useful" identifiers from package documentation. These include:

• unexporting them (when possible),
• moving them into an /internal/ package,
• adding more detailed and helpful documentation to the important identifiers, less documentation to the less important identifiers.

Implementing a new mechanism to hide identifiers sounds like a very ambitious undertaking, and it's hard to be sure it won't have negative side-effects. For example, some users may disagree with package author about what they think is important to see documentation for. They might also get confused as to why some exported identifiers in the code don't show up in godoc.

Perhaps this is the kind of change that makes sense to consider and discuss in the context of Go 2.

[buchanae]

If there's a reasonable approach to hiding json tags and Marshal* methods for a large number of struct types, I'd be glad to use it, however I can't think of one.

I share your concerns about potentially negative side-effects, but I think there are reasonable solutions. A simple Javascript toggle could be used to show/hide these low-level details. Another idea would be to substantially deemphasize these low-level details, instead of hiding them completely.

Of course, I always have the option to generate documentation tailored to my package outside of gddo, but that's also ambitious, and possibly loses the familiarity of gddo.

[dmitshur]

Of course, I always have the option to generate documentation tailored to my package outside of gddo, but that's also ambitious, and possibly loses the familiarity of gddo.

I've seen this done in the past for a moderately sized collection of Go packages. The change there was primarily about customizing the look and feel (fonts, CSS, etc.) of the docs. Eventually, that project reverted to just relying on godoc.org to simplify things.

However, I think this kind of a change is best prototyped and tested out outside of godoc.org itself. It's hard to know how well it'll work, and it's hard to test such a significant change right away on godoc.org. But if an external prototype shows promise, it becomes a more realistic (though still not easy or guaranteed) task to try to upstream that change (if it's generally applicable to all Go packages).

As I understand it, the current scope of godoc.org is to roughly mirror/copy the godoc command behavior (e.g., the same as what you see at https://golang.org/pkg/), but for all import paths. It tries not to deviate too much from the godoc command in look and feel, nor in features.