How to create Javadoc comments

This document is a summary of the information found on the Oracle website:

http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html

My goal is to give you a summarized version of the following topics:

·         What is Javadoc and why is it needed?
·         How to document your code using Javadoc
·         How to generate Javadoc documentation
·         How to publish Javadoc

What is Javadoc and why is it needed?

In simple terms, Javadoc is a tool for documenting your code in HTML format. Because this documentation is in HTML, it can be easily uploaded to a web server and made available online for the whole world to see. An example of this is the Java API (https://docs.oracle.com/javase/8/docs/api/).

For many developers, one of the selling points of Java over other languages like C++ was in fact Javadoc. Why? If you consider one of the most common libraries in C++, stdio, most of the documentation found online is created by third parties. That is, someone else other than the author took the time to document what this library does. Although this is a very nice gesture, wouldn’t be best if the actual author documents what a particular library offers? Javadoc helps developers to document the code as it is being developed.

Publishing Javadoc enables you explaining to the world what a particular package, class, and method does or offers. The level of detail is completely up to you. Consider the following information found on the Javadoc for the Object’s equals method:

public boolean equals(Object obj)

Indicates whether some other object is "equal to" this one.

The equals method implements an equivalence relation on non-null object references:

·         It is reflexive: for any non-null reference value x, x.equals(x) should return true.
·         It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
·         It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
·         It is consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
·         For any non-null reference value x, x.equals(null) should return false.

The equals method for class Object implements the most discriminating possible equivalence relation on objects; that is, for any non-null reference values x and y, this method returns true if and only if x and y refer to the same object (x == y has the value true).

Note that it is generally necessary to override the hashCode method whenever this method is overridden, so as to maintain the general contract for the hashCode method, which states that equal objects must have equal hash codes.

Parameters:obj - the reference object with which to compare.Returns:true if this object is the same as the obj argument; false otherwise.See Also:hashCode(), HashMap

The Javadoc entry starts by giving a very clear definition of the intent of the method: “Indicates whether some other object is "equal to" this one. The equals method implements an equivalence relation on non-null object references.” Then, it goes into detailing the 5 cases to establish equality (or non-equality) between two objects. With this example you can see that the reason behind providing Javadoc is to give future users of your code insight on how to use (or not to use) your published classes and methods.

How to document your code using Javadoc

The first thing you should be aware of is the syntax for Javadoc. Javadoc are added to certain parts of the source file to document parts of the code. In all cases, Javadoc is simply a specialized form of a comment. It can be added at the class level, at the method level, or at the data member level. In Java, a code comment can be created by adding “//” at the beginning of each line (line comment), or in between “/* */” for a block comment. Javadoc comments looks slightly similar to a block comment. To add Javadoc comment, simply add “/**” at the beginning of the comment and “*/” at the end. Therefore, a Javadoc comment is enclosed between “/** */”. As an example:

/**
 * This class overrides the behavior or ArrayList and allows objects to be stored in 
 * a Last-In, First-Out (LISO) data structure 
 * 
 * @author Hector Fontanez
 *
 */
public final class MyStack extends ArrayList<Object> {...}

Notice that this comment placed above the class declaration is the Javadoc comment for the class. So, to document a particular variable, method, etc., simply place the Javadoc comment directly above the part of the code you wish to document. Because the intent of Javadoc is to inform the outside world how to use your provided classes and methods, it is only necessary to add Javadoc to public and protected entities. Since private entities are only accessible internally, they do not need Javadoc. Also, for the same reason, default (package-private) entities need not to be documented.

In Eclipse, hovering over a particular class, variable, or method name reveals the Javadoc for the entity if one exists. In the case of MyStack, hovering over the class name, reveals its Javadoc comment, like so:

In Eclipse, when documenting a method, the parameters list is automatically detected after hitting ‘ENTER’ right after typing “/**”. For instance, for the MyStack method below:

/**
 * Inserts element to top of MyStack
 * 
 * @param e The object to be inserted
 */
public void push(Object e) {
 add(size++, e);
}

The annotation @param with the value of ‘e’ was automatically generated. All I had to do was to provide a brief explanation as to what this parameter represents.
Documenting your code is not as easy as it might look. The natural tendency is not to be very specific because, being the author, the code makes sense to you and you feel as it needs no explanation. In a good development team, this becomes a reviewable item. This means that you will get feedback from others as to the usefulness of your provided documentation. Remember, you do not write code for yourself, you write it for others to use. And because of that, your documentation has to make sense and be useful to others; not to yourself.

How to generate Javadoc documentation

Integrated Development Environments such as Eclipse make it easier to generate Javadoc. It is as simple as this:

On the top menu, simply select Project, and Generate Javadoc… In the Generate Javadoc Window (see below) you can select which projects, packages, and classes you want to generate Javadocs for.

You can also generate Javadoc from the command console. The javadoc.exe command can be executed using the following syntax:

javadoc [ options ] [ packagenames ] [ sourcefilenames ] [ -subpackages pkg1:pkg2:... ] [ @argfiles ]

For example:

javadoc -d \home\html -sourcepath \home\src -subpackages java -exclude java.net:java.lang

This example uses -sourcepath so javadoc can be run from any directory and -subpackages for recursion. It traverses the subpackages of the java directory excluding packages rooted at java.net and java.lang. Using the command console to generate Javadoc could be very handy if you are planning to create scripts that can generate and publish Javadoc automatically during the build process. For more information on how to use the command console to generate Javadoc, see the Oracle’s Javadoc website

One thing to keep in mind is that the command to create Javadoc (javadoc.exe) is part of the Java Development Kit (JDK) not part of the runtime environment (JRE). Therefore, the location of the javadoc.exe is inside the JDK folder. If you did not download the JDK, you cannot generate the Javadoc HTML files. However, you can still add the Javadoc comments to the source code, and generate the HTML files later.

How to publish Javadoc

The obvious answer to this question is to post them on the Internet, like in the case of Java. However, there might be reasons not to make Javadoc public knowledge. For example, the code you created might be exclusively for a particular client that might not wish any part of the code be known publicly. You can still package the Javadoc with the deliverable package to the customer. After I generated Javadoc using Eclipse, the following folder structure was generated:

The main point of entry to the entire set of comments is the index.html file. Opening the file yields amazing results:

My documentation not only looks professional, but it fully functional. It contains an index on the left pane that could be hidden if the “no frames” option is selected, and the index contains hyperlinks to other classes and packages. It also contains other information I did not have to explicitly include. For instance, the class hierarchy it belongs to. In the case of MyStack, you can see that ArrayList is the immediate parent, which is part of the Java’s Collections API and eventually goes up to Object. Since the documentation should be happening as the code is being developed, Javadoc is a way to guarantee your code is self-documented. Another advantage of documenting as you code, is that you do not have to wait until you have forgotten why the class was created and what does it do. Doing the documentation as you code is the best way to ensure the source code documentation is as accurate as it could possibly be.