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

Comments

Projects
None yet
5 participants
@griesemer
Contributor

griesemer commented Jan 13, 2014

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).

@griesemer griesemer added new labels Jan 13, 2014

@bradfitz bradfitz removed the new label Dec 18, 2014

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

@rsc rsc removed release-none labels Apr 10, 2015

@rsc rsc changed the title from cmd/godoc: should exploit information provided by source file organisation to 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

This comment has been minimized.

Member

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

This comment has been minimized.

Member

agnivade commented Jun 20, 2018

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.

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