30.3. Javadoc

30.3.1. Writing Javadoc

Existing Javadoc documentation is available on-line at: http://base.thep.lu.se/chrome/site/doc/api/index.html.

The BASE API is divided into four different parts on the package level.

Introduction to the Base API and it's parts can be found on the start page of Base Javadoc. Plugin developers and other external developers should pay most attention to the public API. What we consider to be the public part of the API is discussed in Section 29.1, “The Public API of BASE”.

30.3.1. Writing Javadoc

This section only covers Javadoc comments, how to write proper none-Javadoc comments are described in Section 31.3.2, “General coding style guidelines”

General information about Javadoc and how it is written in a proper way can be found at http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html. The rule when coding in Base is that all packages, classes, interfaces, public methods and public attributes must be commented in Javadoc style. It is also recommended that private and protected methods has some comments, but maybe not as detailed as the public ones. Below follow more specific details what to have in mind when writing Javadoc in the Base project.

General

General things that are common for all Javadoc comments in Base.

  • All comments should be in English.

  • Do not start each new line of comment with a star.

  • If a comment is mostly related to the inner workings of BASE, it should be tagged with

    @base.internal

Package comments

Package comments should be placed in a file named package.html in the source code directory.

[Important] Is the package public or internal?

This information should be added in the package.html file. You must also modify the build.xml file. The doc.javadoc target contains <group> tags which lists all packages that are part of each group.

Class and interface comments

A comment for a class or interface should start with a general description. The class comment should then give information about what the class can be used for, while an interface comment more should inform which kinds of classes that are supposed to implement the interface.

@author

The first name of the author(s) of the class.

@since

The BASE verion when this class or interface was added.

@see

Optional. Links to some related subjects.

@base.modified

Optional. Some classes has this tag too. This is for give the class-file a time stamp when it is checked in to subversion.

Method comments

A method comment should start with a general description of the method and what it does. The following tags must be present in this order:

@param

One tag for each parameter of the method. Make sure to tell what values are allowed and what will happen if a disallowed value is passed.

@return

What is returned by the method. Make sure to tell what values can be returned (ie. if it can be null).

@throws

One tag for each exception that the method can throw and describe when and why it will be thrown.

@since

Use only this tag together with methods added in a later version then the one the class was created in. It holds which version the method first was available in.

@see

Optional. Link to relevant information, one tag for each link.

Attribute comments

If the attribute is a static final, describe what the attribute is for an where it is typically used. Other attributes can often be explained through their getter and setter methods.