Documentation is key when programming. There is the documentation in the code itself such as what the heck you're trying to do there. There is also the documentation that describes the functions and objects and how to use them. Luckily there is a tool that helps the programmer create nice HTML documentation based on the comments within the code. This knocks out two birds with one stone. Javadoc is the tool to use for this task. There is also PHPdoc as well for, you guessed it PHP.
For this entry we'll only be concerned about Javadoc.
The syntax for creating documentation is very simple and straight forward.
/**
* Returns a String that contains the database address.
* All arguments are in the form of a {@link String}. The hostname is the full path to the database server.
* The user variable contains the specified user. The passwd variable is the variable that contains the password
* the user.
*
* This function will throw an exception if for some reason it fails.
*
* @param hostname full URL to the database.
* @param user user name that is to be used to log in.
* @param passwd password to use along with the user.
* @return The connection string used to connect to a database.
* @throws Exception containing why the function failed.
* @see String
*/
- The '/**' indicates that this is to be made into documentation.
- The first sentence will be displayed in the summary that is printed in the method summary and index table.
- If there is more than one paragraph then you need to specify it by using the '' tag. This tag does not need a closing tag ('
).
- The first line that begins with '@' ends the description. Everything after that is a special item, such as param, throws, return, see, and so on.
- To end the documentation there is only a '*/.'
When writing documenation there is no need to retype anything if a function is overridden.
Style Guide
Use the
..
when mentioning any of the following:
- Java keywords
- package names
- class names
- method names
- interface names
- field names
- argument names
- code examples
Links should only be used once, providing that you feel the user may want to click on it.
If a function is overloaded and you are referring to a single function, then refer to it with parentheses containing the parameter types. add(int, Object). To reference a function generally then refer to just the name of the function add.
Describe what is going on in third person.
Method descriptions begin with verbs.
Class/Interface/Field describe what they are rather then the action. So a simple "A button label." is all that you need.
Add description beyond the self-documenting name of the method. Instead of:
Sets the label text.
Use:
Sets the label text and applies an image behind the text.
Tags
There is a specific order in which the tags should be listed at the end of the documentation.
- @param - used for classes, interfaces, methods and constructors only. If there is more than one parameter then they are listed in the order that they are declared in. When describing a parameter, use the name of the parameter, not the data type. The first letter in the description should not be capitalized.
- @return - methods only and is required if the method returns something other than void.
- @throws (was @exception) - The type of exception should be named. Any exceptions thrown should be listed in alphabetical order.
- @author - used for classes and interfaces only and is required. If there are more than on author then they should be listed in chronological order.
- @version - used for classes and interfaces only and is required.
- @see - If there are more than one see then each item should be listed from nearest to furthest access.
@see #field @see #Constructor(Type, Type...) @see #Constructor(Type id, Type id...) @see #method(Type, Type,...) @see #method(Type id, Type, id...) @see Class @see Class#field @see Class#Constructor(Type, Type...) @see Class#Constructor(Type id, Type id) @see Class#method(Type, Type,...) @see Class#method(Type id, Type id,...) @see package.Class @see package.Class#field< @see package.Class#Constructor(Type, Type...) @see package.Class#Constructor(Type id, Type id) @see package.Class#method(Type, Type,...) @see package.Class#method(Type id, Type, id) @see package @since @serial @depreciated