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.
Public API - All classes and methods in the package are public. May be used by client applications and plug-ins. In general, backwards compatibility will be maintained.
Extension API - All classes and methods in the package intended for internal extensions only. Not part of the public API and should not be used by client applications or plug-in.
Internal API - All classes and methods in the package are internal. Should never be used by client application or plug-ins.
Mixed Public and Internal API - Contains a mix of public and internal classes. Check the Javadoc for each class/method before using it.
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”.
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://java.sun.com/j2se/javadoc/writingdoccomments/index.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 only should be shown in the internal documentation and not in the public, it should be tagged with
@base.internal
- Package comments
-
Package comments should be placed in a file named
package.htmlin the source code directory.![[Important]](../../gfx/admonitions/important.gif)
Is the package public or internal? This information should be added in the
package.htmlfile. You must also modify thebuild.xmlfile. 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.
@version
From which version of Base the class is available.
@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.