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/tools/cmd/godoc: should exploit information provided by source file organisation #7116

Open
griesemer opened this issue Jan 13, 2014 · 2 comments
Labels
NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Milestone

Comments

@griesemer
Copy link
Contributor

When creating documentation, godoc ignores the organization of the source code into
files. Larger packages are usually split into separate files, with each file covering a
certain aspect of the package, and sometimes also the package's API.

For instance, go.tools/go/types API defines a set of "Object" and
"Type" types, which are grouped into separate files (objects.go, types.go).
godoc simply groups all types alphabetically and thus the original grouping which does
help understanding is lost.

We should come up with a mechanism to exploit this information if possible; ideally w/o
introducing mechanism for the programmer (but perhaps a convention).
@bradfitz bradfitz removed the new label Dec 18, 2014
@rsc rsc added this to the Unplanned milestone Apr 10, 2015
@rsc rsc changed the title cmd/godoc: should exploit information provided by source file organisation x/tools/cmd/godoc: should exploit information provided by source file organisation Apr 14, 2015
@rsc rsc removed the repo-tools label Apr 14, 2015
@meirf
Copy link
Contributor

meirf commented Jun 20, 2018

When the Index section is expanded, we could have a toggle for sorting by file. When toggled, all members in the index could be grouped by the file they are defined in (in order of file name alphabetically). The file name could be slightly highlighted as a not-so-large header before its index contents. This brings up a some concerns:

  • Would sorting affect just the index or also the documentation below?
  • What happens for methods (on e.g. structs) where methods on a single type can span multiple files? I suppose we could just have type Basic and func (b *Basic) Info() BasicInfo in one section and func (b *Basic) Kind() BasicKind (assuming for argument that BasicKind was in another file.)
  • Would giving respect like this to file organization encourage larger packages/packages with more files? Maybe that's okay.

@agnivade I wonder if you have thoughts on this/other solutions.

(When this issue was created, godoc already had the "Package files" section so that's certainly not a solution to this. Not to mention that section links to source files (not godoc) and is also not a "mechanism".)

@agnivade
Copy link
Contributor

This issue is difficult to tackle as we have to apply lot of heuristics to get it right, and different users organize their files in their own way, as you have pointed out. Currently, godoc shows the documentation in a consistent way which is important when the user is working with multiple projects of varying styles. Changing the rendered output depending on the source file organization is too brittle and prone to change, the moment somebody shifts code around.

If the aim for godoc is to expose human organisation of the source code, I would argue that adding hotlinks and sections (not just ToC, but a magic word for sections which group related functions and types together #18342 (comment)) provide a better solution to this. We can let those happen first, and then come back and revisit this IMO.

@seankhliao seankhliao added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Jul 13, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Projects
None yet
Development

No branches or pull requests

6 participants