Introduction
This article tries to summarize the basics of Javadoc: Importance, basic usage and tags reference to create documentation for the existing two types: Usage documentation and Implementation documentation.
Background
The Usage documentation is aimed at users that need to understand the functionality of a code and how to use it on their own code, but they really don't need to know how the implementation works. Let's use any API as an example, to use it on your code, you just need to know what needs to be sent and what is returned, how the code does the job is not really necessary in this case.
The Implementation documentation aims for the user that needs detailed descriptions on how the functionality is implemented on each method, it very useful for those who maintain, enhance or debug the code.
Is it important to use both types of documentation? The answer is a big solid YES. It is one of the best practices you should be implementing on your code. When you create code, nobody except you knows what it does and how it should be used, if someone needs your code, it will not be so easy to understand it quickly and let's say that you need that code 3 months later, probably you will not remember it. Additionally, using Javadoc, you can generate external documentation, very useful as a public reference.
Using the Code
What should have documentation?
Well, everything can have documentation, but for least there are 3 areas where the documentation is required (it doesn't matter if they're public
, protected
or private
):
- Classes
- Constants, Variables
- Methods
Here is a reference of the code, syntax and tags to do basic documentation.
Special Characters
First of all, in your documentation, you should escape special characters that have special meaning in HTML, for example &, < and >, in this case:
- Change & to &
- Change < to <
- Change > to >
Other special characters that need escape are:
- ® (®)
- Á (Á)
- á (á)
- ñ (ñ)
Remember there are a lot of these characters, you can use this table as a reference for the rest of them. Notice that Javadoc is like writing a HTML, you can use tags like <a href>
, <p>
, <br>
and others.
Javadoc Tags
There are tags for several purposes, here are some of them and where to use them:
@author
Use this tag to describe the author.
Applies to: Classes, Interfaces and Enums
Example:
public class MyLittleClass{...}
Taking advantage of HTML tags, you can use something more elaborated like:
public class MyLittleClass{...}
@version
Use it to provide the version of the software.
Applies to: Classes, Interfaces and Enums
Examples:
public class MyLittleClass{...}
public class MyLittleClass{...}
@since
Use it to describe the first appearance of a functionality.
Applies to: Classes, Interfaces, Enums, fields and methods.
Examples:
public class MyLittleClass{...}
public class MyLittleClass{...}
@see
Use it to make reference of other elements of documentation.
Applies to: Classes, Interfaces, Enums, fields and methods.
Examples:
Referencing a class or interface:
public class MyLittleClass{...}
Referencing a method of a class or interface (also use #
to access variables of the class and YourClass#yourMethodOrField to reference the method/field of other classes)
public void addUsingExtraSteps(Object object, int i){...}
@param
Use it to describe a parameter of a method.
Applies to: Methods.
Example:
public void renameFile(File file, String newName){...}
@return
Use it to describe a return value.
Applies to: Methods.
Example:
public String encrypt(String password){...}
@throws or @exception
Use it to describe an exception that may be thrown by the current method.
Applies to: Methods.
public File getFile(String path) throws FileNotFoundException {…}
@deprecated
Use it to describe a class, field or method as outdated.
Applies to: Classes, Interfaces, Enums, fields and methods.
Examples:
public String encrypt(String password){...}
public class MyLittleClass{...}
{@inheritDoc}
Use it when you want to copy the description from the overridden method.
Applies to: Overriding Methods.
@Override
public String encrypt(String password){...}
{@link}
Use it when you want to link to other symbols (class, method, field). Remember that using #
shows you the methods of fields of a class.
Applies to: Classes, Interfaces, Enums, fields and methods.
Examples:
public class MyNewLittleClass{...}
{@value #STATIC_FIELD}
Use it to print the value of a static
variable (constants).
Applies to: Classes, Interfaces, Enums, fields and methods, but only making reference of a static field.
public class MyLittleClass{...}
Points of Interest
Something I notice everyday is that most of the times, the names of classes and methods are very clear on what they do, BUT it is not an excuse for not doing its documentation!
Also, do not extend the content of the documentation too much, especially for the Implementation one, otherwise the code becomes hard to read.
History
- 24th September, 2013: Created the article