Documentation Guidelines

Overview

1. documentation must be written in english
2. at least 90% public API javadoc documentation density must be reached for new code. This includes public, protected and package protected (default) visibility of
   • all classes, interfaces, enums, methods
   • all method and constructor parameters
   • all method return values
   • all thrown Exceptions
3. the Javadoc must be meaningful and concise. It must allow a newcomer to understand quickly
   • the responsibility of the class, interface
   • the role of an enum
   • what a method is doing (and not how it is doing it)
4. when adding a new package, create a package-info.java file inside the package and explain its role, what type of files should be put inside it
5. before committing the code, javadoc generation must be checked (see below)
6. complex algorithms must be documented

Testing javadoc generation

Contributors need to know that all F/OSS QualInsight Java projects are published to Maven Central. As such, when releasing the project, the Maven build won't pass if some Javadoc is missing. That's why we ask contributors to test if Javadoc generation completes successfully prior to committing code. All QualInsight projects are configured in order to ease this task. All you have to do is to run the following command and read the logs:

mvn javadoc:jar