Learn Java for Android Development: Javadoc Code Documentation 9/13

This quick lesson covers Javadoc, a helpful tool for generating documentation from your Java source files. This lesson is part of an ongoing series of tutorials for developers learning Java in order to develop Android applications.

What is Javadoc?

Javadoc is a utility provided with the Java SDK that allows developers to generate code documentation from Java source files. Development environments like Eclipse have built-in support for Javadoc and can generate searchable HTML reference materials from Javadoc-style comments. In fact, the Android SDK reference is a form of Javadoc documentation.

How Does Javadoc Work?

Javadoc documentation uses a combination of processing the source code (and inspecting types, parameters, etc.) and reading special comment tags that the developer provides as metadata associated with a section of code.

A Javadoc-style comment must come just before the code it is associated with. For example, a Javadoc comment for a class should be just above the class declaration and a comment for a method should be just above the method declaration. Each comment should begin with a short description, followed by an option longer description. Then you can include an number of different metadata tags, which must be supplied in a specific order. Some important tags include:

• @author – who wrote this code
• @version – when was it changed
• @param – describe method parameters
• @return – describe method return values
• @throws – describe exceptions thrown
• @see – link to other, related items (e.g. “See also…”)
• @since – describe when code was introduced (e.g. API Level)
• @deprecated - describe deprecated item and what alternative to use instead

You can also create your own custom tags for use in documentation.

Generate Javadoc-style Comments in Eclipse

While you are writing code in Eclipse, you can generate a Javadoc –style comment by selecting the item you want to comment (a class name, method name, etc.) and pressing Alt-Shift-J (Cmd-Shift-J on a Mac). This will create a basic Javadoc-style comment for you to fill in the details.

Simple Javadoc Class Comments

Let’s look at an example. Here’s a simple Javadoc comment that describes a class:

/**
 * Activity for loading layout resources
 * 
 * This activity is used to display different layout resources for a tutorial on user interface design.
 * 
 * @author LED
 * @version 2010.1105
 * @since 1.0
 */
public class LayoutActivity extends Activity {

Here’s what it will look like when you generate the Javadoc documentation:

Simple Javadoc Field Comments

Let’s look at an example. Here’s a simple Javadoc comment that describes a field within a class:

/**
 * Debug Tag for use logging debug output to LogCat 
 */
private static final String DEBUG_TAG = "MyActivityDebugTag";

Here’s what it will look like when you generate the Javadoc documentation:

Simple Javadoc Method Comments

Now let’s look at two examples of method comments. Here’s a simple Javadoc comment that describes a method within a class:

    /**
     * Method that adds two integers together
     * 
     * @param a The first integer to add
     * @param b The second integer to add
     * @return The resulting sum of a and b
     */
    public int addIntegers(int a, int b)
    {
        return (a+b);
    }

Now let’s look at a method that returns void, but throws an exception:

    /**
     * This method simply throws an Exception if the incoming parameter a is not a positive number, just for fun.
     * 
     * @param a Whether or not to throw an exception
     * @throws Exception
     */
    public void throwException(boolean shouldThrow) throws Exception
    {
        if(shouldThrow == true)
        {
            throw new Exception();
        }
    }

Here’s what it will look like when you generate the Javadoc documentation for these two methods:

Generating Javadoc Documentation in Eclipse

To generate Javadoc code documentation in Eclipse, go to the Project menu and choose the “Generate Javadoc…” option. This will launch a wizard that allows you to choose the projects to generate documentation for.

From this wizard, you should point Eclipse at the appropriate javadoc.exe command line tool (you’ll find it in your JDK’s /bin directory). You can also configure some documentation settings, such as whether to document all code, or only visible classes, members, etc. Finally, choose a destination for your documentation files.

Even without generating the Javadoc files, Eclipse will show the Javadoc-style documentation when you hover over your methods and such, as shown in the figure below.

Learning More about Javadoc

You can find out more from the Javadoc reference at the Oracle website. There is also a helpful Javadoc FAQ available.

Conclusion

In this quick lesson you have learned about Javadoc, a powerful tool used by Java developers to document source code thoroughly for reference and maintenance purposes. Eclipse, the development environment used by many Android developers, has built-in support for Javadoc.

Source: Tutsplus.com