In my personal experience, examples do a poor job of explaining the reasoning behind something or the big picture behind something. It depends on the project, obviously, but often examples are fine for simple things but really don’t help with big complex things. Often they also don’t explain the trade offs or when you might choose a the various different options.
In my opinion, good documentation has three parts (four if you include a tutorial too):
First is a document explaining rationale, high level/big picture design, tradeoffs, when to use what. Usually a prose document with some sample code snippets where appropriate. Second, example code showing how to solve different use cases. Finally, an api reference (often auto generated from docstrings).
Different projects need different levels of each of these. For example, a relatively simple library might get away with a few short paragraphs for the prose documentation and maybe the api reference is literally just listing the public functions (if the names and parameter names are descriptive), this can be generated without any additional markup. If the api is complex, then it may need some explanation. Or the text documentation needs to be more detailed.
Obviously I don’t expect this from everyone who release some code online. For small code snippets, I’m happy with a commented example use and appreciative that you released the code at all. However, don’t be surprised if your code doesn’t get used then and if you want me to contribute, then I need to understand your project and without documentation I can’t do that. If I don’t understand your project, I risk that any PR I do is wasted effort and my time is limited (but I’ll happily help projects I use out regardless, where I can. I may need some guidance though)
From my experience there’s little to no correlation at all.
One of the most beautiful C codebases I’ve seen - the SSH IPsec stack - had the most succinct yet comprehensive documentation. Linux kernel has virtually none of the latter but the quality is still very high. Then there’s something like Miranda IM - complete clusterfuck of the code, but really well documented. A lot Java code is that way too, but also with documentation rehashing trivial facts rather than explaining anything.
However, what does seem like a sign of a good code is longer intro comments in header files that explain the design rationale and how things fit together in general. It’s basically a level up from verbose API description, but when done right it makes the API obvious without any further detailing.
