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

cmd/godoc: consider listing package abbreviations in generated docs #4722

Closed
dsymonds opened this issue Jan 29, 2013 · 13 comments
Closed

cmd/godoc: consider listing package abbreviations in generated docs #4722

dsymonds opened this issue Jan 29, 2013 · 13 comments
Labels
Documentation Issues describing a change to documentation. FrozenDueToAge

Comments

@dsymonds
Copy link
Contributor

Right now, you can get docs that look like
  func DoSomething(x *pog.Something) error
and have no idea what "pog" is, even if the package hasn't renamed it.

I propose that godoc render a list of the imports of a package where (1) the import path
does not match the local name (either renamed, or because the import path is
whatever/blah/de/blah), and (2) the package uses the imported package in its exported
API.

At the end of the package overview, generate a small block like:
  In this package's API,
    pog is github.com/foo/pog
    http is net/http
    ...

This is especially important for the docs of a non-standard-library package that uses
types from another non-standard-library package. My (1) condition excludes things like
io.Reader (but would capture net/http.Request), so I don't think it would be burdensome.
@rsc
Copy link
Contributor

rsc commented Jan 30, 2013

Comment 1:

Labels changed: added priority-later, removed priority-triage.

Status changed to Thinking.

@rsc
Copy link
Contributor

rsc commented Mar 12, 2013

Comment 2:

[The time for maybe has passed.]

Labels changed: removed go1.1maybe.

@adg
Copy link
Contributor

adg commented Mar 18, 2013

Comment 3:

Labels changed: added godoc.

@rsc
Copy link
Contributor

rsc commented Jul 30, 2013

Comment 4:

Labels changed: added go1.2maybe.

@rsc
Copy link
Contributor

rsc commented Jul 30, 2013

Comment 5:

Labels changed: added feature.

@robpike
Copy link
Contributor

robpike commented Aug 19, 2013

Comment 6:

Won't happen for 1.2

Labels changed: added go1.3maybe, removed go1.2maybe.

@robpike
Copy link
Contributor

robpike commented Aug 20, 2013

Comment 7:

Labels changed: removed go1.3maybe.

@rsc
Copy link
Contributor

rsc commented Nov 27, 2013

Comment 8:

Labels changed: added go1.3maybe.

@rsc
Copy link
Contributor

rsc commented Nov 27, 2013

Comment 9:

Labels changed: removed feature.

@rsc
Copy link
Contributor

rsc commented Dec 4, 2013

Comment 10:

Labels changed: added release-none, removed go1.3maybe.

@rsc
Copy link
Contributor

rsc commented Dec 4, 2013

Comment 11:

Labels changed: added repo-tools.

@dsymonds
Copy link
Contributor Author

dsymonds commented Dec 4, 2013

Comment 12:

This might be mostly moot now that godoc will render links to the right package.

@adg
Copy link
Contributor

adg commented Dec 4, 2013

Comment 13:

Status changed to Retracted.

@dsymonds dsymonds added retracted Documentation Issues describing a change to documentation. labels Dec 4, 2013
@golang golang locked and limited conversation to collaborators Jun 24, 2016
This issue was closed.
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Documentation Issues describing a change to documentation. FrozenDueToAge
Projects
None yet
Development

No branches or pull requests

6 participants