x/tools/cmd/godoc: should exploit information provided by source file organisation #7116
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).
changed the title
cmd/godoc: should exploit information provided by source file organisation
Apr 14, 2015
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:
@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".)
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.