Chapter 1. JavaDoc

Table of Contents

JavaDoc Tags
Tagging classes
Tagging procedures
DocbookDoclet
JavaDoc Statistics
Keyword Index

Most of the documentation about the CDK classes is done in the java source files itself. The format used for this is the JavaDoc format. An overview/introduction can be found at http://java.sun.com/j2se/javadoc/writingdoccomments/.

JavaDoc documentation is now generated using Javadoc and Ant:

cdk/$ ant -buildfile javadoc.xml html
        

JavaDoc Tags

The two sub sections contain suggested policy and is not yet as such approved.

Tagging classes

Java classes should have the JavaDoc tags @copyright and @author. In addition, the CDK specific tags are available.

CDK specific JavaDoc tags

@cdk.created

The date on which the class was created. Should be in the format YYYY-MM-DD.

@cdk.module

Indicates the CDK module to which this class belongs. If not given, then the extra module is implied.

@cdk.keyword

Indicates a keyword for this class allowing users to find the class more easily. More than one tag may be used. The index is found online.

@cdk.builddepends

Indicates on which jar files this class depends on runtime.

@cdk.depends

Indicates the which jar files are required to compile its java source code to a class.

@cdk.bug

Lists an open bug as reported on SourceForge. It is automatically linked to the SF bug list for the CDK project. One tag for one bug.

@cdk.require

Defines a build requirement. Examples requirements are 'java1.4' indicting that the class can only be compiled with java1.4, 'java1.4+' that it can be compiled with Java 1.4 or better, 'ant1.6' which requires Ant 1.6 to get this class compiled, and 'r-project' which requires the R to be present.

Tagging procedures

Procedures of classes should give information about what they do and information about parameters (@param) and things they return (@return).

If the procedure performs a method found in literature, it should mention the reference. No format for the reference has been determined, but the BibTex format, or a link to http://cdk.sf.net/biblio.html#ARTID should do fine.