But what I have not found yet (or discovered for myself) is good guidance on how to document larger blocks of code. If a function is more than a few lines long, I haven't found a satisfactory way to document it.
The first approach I tried was not to respect the atomicity of the function in terms of formatting. That is, I would just write along literately about what the function was doing, right inside the function. The problem is that in both the code and the generated documentation, it becomes very difficult to discern scope visually.
The second approach I tried was to give a brief overview description above the function, then include ordinary comments inside it. That's fine and all, but at that point, you're not gaining much over simple block comments above the function.
The third approach I've tried is to either use an ordered list of steps preceding the function, or to describe the function with numbered footnotes, and then to add corresponding numeric comments in the code. This is the most satisfactory solution I've found yet, and the documentation ends up looking like a programming book. But the locality of reference is just terrible. It's also just terrible for control flow statements. Using an outline format instead of an ordered list can allow for a bit better control flow, but it's still not great.