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: support company-specific doc annotations #8586

Open
bradfitz opened this Issue Aug 25, 2014 · 3 comments

Comments

Projects
None yet
3 participants
@bradfitz
Member

bradfitz commented Aug 25, 2014

Google internally runs a godoc server serving docs for the standard library + all of
Google $GOPATH (all internal Google Go code).

In many cases, we'd like to mention the Google-specific libraries or ways of doing
things from the standard library docs.

It would be nice if there were a file we could maintain that appended company-specific
doc annotations to the standard library on at least:

-- packages
-- funcs
-- types
-- specific fields on struct types
@adg

This comment has been minimized.

Contributor

adg commented Aug 26, 2014

Comment 1:

We could also just modify the source tree internally at Google, rather than adding a
bunch of hooks to godoc.
@bradfitz

This comment has been minimized.

Member

bradfitz commented Aug 26, 2014

Comment 2:

That's a possibility.
But doing it naively with patch files that would go stale over time as the standard
library changes would be a pain, so we'd want to not use diff+patch and an go/*-based
AST patcher instead. Once we have that, the godoc hooks aren't much more work and could
benefit other companies. Google's not unique in this regard.
@adg

This comment has been minimized.

Contributor

adg commented Aug 27, 2014

Comment 3:

A general tool for patching doc comments would also be generally useful. :-)
Either way it's done, the source format ("add this annotation to this doc comment") will
be the same.

@rsc rsc added this to the Unplanned milestone Apr 10, 2015

@rsc rsc removed accepted labels Apr 14, 2015

@rsc rsc changed the title from cmd/godoc: support company-specific doc annotations to x/tools/cmd/godoc: support company-specific doc annotations Apr 14, 2015

@rsc rsc removed the repo-tools label Apr 14, 2015

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment