See for example this package comment: https://github.com/golang/go/blob/master/src/net/http/doc.go...
Turns into this documentation (the beginning only): https://godoc.org/net/http
Out of the box.
// ...// EnqueueEvent ...
func (q *Queue)EnqueueEvent(event Event)
Having a sensible folder structure and good folder names is nice, but taking a few minutes to write individual READMEs can make a repo even easier to understand.
It rarely gives you what is in each folder, and what part of the functionality each folder handles, although perhaps we should try to change the conventions of readme files to include file structure.
edit: I mean the root readme might contain what is in each folder so you don't have to click on each one to see which one you want to start with.
In github, rather than see what has changed, it would be interesting if there was a comment that told you what the folder contained.
edit: Relevant here because the best codebase for me is one where I can understand the folder structure, but that is a sort of 0th order effect that should be equalized with some tool.