Java developers’ IDEs already provide direct access to the Javadoc. So this idea addresses one justification for printable documentation — you can keep reading even when offline — preventing you from having to search. At the same time you can still find the Javadoc we post with an online search. Committing doc into the code also makes it slightly easier for SDK builders like Matt to notice when making a change that affects the documentation.
Perhaps most importantly this idea leads to the “dev guide” matching the modules you actually use. In other words, if we put dev guides in the Javadoc, then when you build a Maven project that grabs org.forgerock.json.resource, i18n-framework, opendj-ldap-sdk, you get just the doc you need without having to leave your IDE. Not only lists of packages, classes, and methods, but also how-tos and so forth.
I’m still figuring out what it means in detail to, “Add the dev guide into the Javadoc.” Clearly not all of the content goes into the code. No doubt a good part of the content sits alongside the body of the code, next to or in
overview.html in the
main/javadoc/ folder of the LDAP SDK source.
What’s your take on the idea?