My problem with code documentation is that documentation is done at the function or class level. When I'm looking at new code I would prefer a "concept of operations" describing how the whole thing works together rather than piecemeal function documentation.
This is especially important with open source code. I'm not going to donate my time to working with an existing codebase if it is going to take hours to figure out how it all pieces together. Examples are fine but what I really need to know is the why. At least when I put up with this at work I'm getting paid by the hour.
The old classic literate programming paradigm helps with this. It allows one to write documentation that gives you an overview, provides you with whatever ordering and connections you feel appropriate and, with my implementation of it, even takes care of most of the tool chain. https://npmjs.org/package/literate-programming
+1 to this, whether I'm making a quick fix or intend to do some significant work, if I'm diving into an unfamiliar project I am always overjoyed if I find 'concepts and metaphors' documentation.
I opened the comments with an intention to write basically the same thing.
Higher level documentation - classes, packages, groups of packages - makes the project much more approachable. It answers the question "Here's a 3 levels deep hierarchy - where do I start, how are the pieces connected to each other?"
Documenting classes is fairly common, but only the public API. I'm not only interested in how to use the class, but also how does it work internally, what is the inner architecture.
Often I find myself wishing that I could see things as a sequence diagram. I've never worked anywhere where functions were commented with useless English descriptions of the parameters and so on, so I don't really know if this is something that people really do. What I do wish I had was more high-level, visual representations of a system when I'm trying to learn how it functions.
In Go, you can put a comment above the package clause in any of a package's source files (including an otherwise empty one) and the tools will pick it up. e.g.:
This is one reason why I really like Doxygen, in the areas where it's supported. It's not only very easy to generate easy-to-read documentation for the code while writing it (specialized comments, with operators to call out special meanings and so forth), but it's also very easy to create high-level documentation from exactly the parts that contribute to it. (Section, page, etc. commands.) Not to mention, then generate a nice, easy HTML stack of it all with pages, search-ability, etc.
I've never really agreed with the whole "code should be just be obvious when read." The problem with any large set of instructions is that both the instruction, order, combinations, and other artifacts reflect the experience, background, and environment of the author. Two developers of largely equivalent experience and talent rarely come up with the same set of instructions for the same task.
Consider if I told you how an engine functioned as a means of telling you how to change a head gasket.
This is especially important with open source code. I'm not going to donate my time to working with an existing codebase if it is going to take hours to figure out how it all pieces together. Examples are fine but what I really need to know is the why. At least when I put up with this at work I'm getting paid by the hour.