That's not the idea. The idea is that you can see relevant examples of how this is used quickly. No need to reflect all. Maintenability is less an issue if you change doc along with the code - javadoc is part of the source code as are also tests, and all them need to be updated as the code changes.