Source Code documentation: what JavaDoc should look like, and why.

Over the years, I have blogged quite a bit about JavaDoc. JavaDoc is the system commonly used to annotate Java source code for human oriented documentation, and complement source code comments. I will not attempt to summarize what I wrote in the past, but will give some links. The primary user of the JavaDoc is, of course, the user:

• Productivity Tool: search bar for any JavaDoc HTML
• The simplest way to make CDK commits

And we take effort in producing good JavaDoc (despite it being the unpaid, least favorite task):

• Cleaner CDK Code #4: inheriting JavaDoc from super classes and interfaces
• Things to check before you consider submitting a (final) CDK patch #1
• Making patches; Attribution; Copyright and License.

And we use tools here to support us:

• Work in Progress: an Open DocCheck replacement
• CACE: computer-aided code evaluation of CDK code
• Call for Collaboration: JavaDoc validation with OpenJavaDocCheck

And using JavaDoc taglets and doclets, we enrich the regular JavaDoc with more detailed information:

• Pimp my JavaDoc
• CDK I/O options in the JavaDoc
• @cdk.githash (JavaDoc HTML links to the source code again)

The CDK uses the JavaDoc not just for documentation, but also for compiler instructions:

• CDK Module dependencies #3