x/tools/cmd/godoc: should exploit information provided by source file organisation

[griesemer]

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

[meirf]

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 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 https://github.com/golang/go/issues/18342#issue-195978097) provide a better solution to this. We can let those happen first, and then come back and revisit this IMO.