So, developers need and want Overview Documentation, and Overview Documentation is not the same thing as Reference Documentation (which is what tools like JavaD

So, developers need and want Overview Documentation, and Overview Documentation is not the same thing as Reference Documentation (which is what tools like JavaDoc produce.) Does anyone find this surprising? Regarding code examples vs test cases: they're different in the same way Overview docs are different from Reference docs. The code examples are part of the overview, and show the typical / most common ways of using the code. The test cases are like reference docs, and show every nuance and feature of the code, including all variations on argument and response types and error paths.