API Documentation and Javadoc Conventions


The specifications for the APIs are captured in the form of Javadoc comments on API packages, interfaces and classes, methods and constructors, and fields. The Javadoc tool (running the standard doclet) extracts these specifications and formats them into browsable form (HTML web pages) which become the reference section of the documentation set describing the Janus projects to ISVs. As a consequence, the bar is significantly higher for API Javadoc than for non-API. Sun's Requirements for Writing Java API Specifications deals with required semantic content of documentation comments for API specifications for the Java platform. All SeT project APIs should follow these conventions.

Sun's How to Write Doc Comments for Javadoc contains style guide and tag conventions for documentation comments. These conventions lead to high-quality code and API documentation. All code written for the Janus projects should follow these conventions except as noted below.

Additional Guidelines

The Janus project has specific guidelines for package, class and interface comments. Each package, class and interface must start the following comment template:

 * comment about this feature.
 * @author $Author: id 1$
 * @author $Author: id 2$
 * @version $Name$ $Revision$ $Date$
 * @mavengroupid $GroupId$
 * @mavenartifactid $ArtifactId$

The commands, which are enclosed by dollar signs, are replaced by the corresponding values from the pom.xml file (if you are using the Maven compilation process). The supported commands are:

  • $Name$: the name of the project.
  • $Revision$: the version number of the project.
  • $Version$: the version number of the project.
  • $Date$: the date of the Javadoc generation.
  • $GroupId$: the identifier of the Maven group of the project.
  • $ArtifactId$: the identifier of the Maven artifact of the project.
  • $Author: id$: the name of the author which was defined in the Maven pom.xml file with the given identifier. See developer tag and contributor tag from the Maven POM Reference.

For example the class fr.utbm.set.gis.util.GISTreeSet:

 * This class describes a quad tree that contains GIS primitives
 * and that permits to find them according to there geo-location.
 * @param <P> is the type of the user data inside the node.
 * @author $Author: sgalland$
 * @version $Name$ $Revision$ $Date$
 * @mavengroupid $GroupId$
 * @mavenartifactid $ArtifactId$
 * @see GISPrimitive
public class GISTreeSet<P extends GISPrimitive> implements Set<P> {

Eclipse Configuration

Your Eclipse Platform should be configured as following: (section "Preferences> Java> Compiler> Javadoc") every options must be set to "Warning" and the visibility level should be set to "Private" or "Default".

To quickly configure your Eclipse IDE, you may import one of the following preferences:

Eclipse Version Janus Headers IRTES-SET Headers CITAT Headers
Galileo zipped-epf zipped-epf
Indigo zipped-epf zipped-epf
Juno zipped-epf zipped-epf
Kepler zipped-epf zipped-epf

Related Pages

2016-01-24SARL 0.3.1 and Janus are available.
2015-11-30SARL 0.3.0 and Janus are available.
This page was last modified on 2 July 2013, at 12:07. This page has been accessed 10,075 times.
Copyright 2010-2017 © Janus Core Developers - Privacy policy