Inleiding tot Java documentatie

Bij het schrijven van programmeercode hoort meestal ook het schrijven van de nodige documentatie. Deze documentatie is van belang voor verschillende redenen. Als eerste, maakt deze het mogelijk om je eigen programmacode nadien (eens na een lange tijd op een ander project te hebben gewerkt) makkelijker terug te kunnen ontcijferen. Verder is het een belangrijke hulp indien een collega-programmeur je programmacode moet aanpassen tijdens jouw afwezigheid. Ten slotte moet ook de klant de nodige documentatie hebben om met de klassen die je ontwikkeld hebt, te kunnen omgaan en ze te integreren in zijn eigen software.

Documentatie voor intern gebruik bestaat meestal uit commentaar bij de programmacode. Voor extern gebruik wordt er doorgaans een document gemaakt met de beschrijving van de publieke klassen en interfaces.

De JDK beschikt over een tool javadoc, die het mogelijk maakt om automatisch de nodige documentatie in HTML5-formaat te genereren van de commentaar bij de programmacode. Deze documentatie heeft een uniforme lay-out zoals we die ook aantreffen bij de JDK-documentatie zelf. Als ontwikkelaar word je daardoor geconfronteerd met een eenvormige manier van API-documentatie.

Meer info op:

• https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html
• https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html