Directory Operations in Java

A directory in Java is a File object that can contain other files and directories. You can use the File class to perform operations such as creating, listing, and deleting directories.

Java - Documentation Using JavaDoc Tool

In this guide, we'll explore the Javadoc tool, which is essential for generating useful documentation from Java source code in HTML format. Starting with Java 9, you can generate documentation in HTML5 format using the -html5 option in the command line.

What is Javadoc?

Javadoc is a tool provided with the JDK that generates HTML documentation from specially formatted comments in Java source code. It's particularly useful for documenting APIs, classes, methods, and other components of Java code.

Example of a Simple Javadoc Comment

Java Source Code


/**
 * The HelloWorld program implements an application that 
 * simply displays "Hello World!" to the standard output.
 *
 * @author Zara Ali
 * @version 1.0
 * @since 2014-03-31
 */
public class HelloWorld {
    public static void main(String[] args) {
        // Prints Hello, World! to the standard output
        System.out.println("Hello World!");
    }
}

Output


Hello World!

Using HTML Tags in Javadoc

Javadoc allows the use of basic HTML tags in the comments. For instance, you can use <h1> for headings and <p> for paragraph breaks.

Java Source Code


/**
 * Hello, World!
 * The HelloWorld program implements an application that
 * displays "Hello World!" to the standard output.
 * 
 * Giving proper comments in your program makes it more user-friendly
 * and is considered high-quality code.
 *
 * @author Zara Ali
 * @version 1.0
 * @since 2014-03-31
 */
public class HelloWorld {
    public static void main(String[] args) {
        // Prints Hello, World! to the standard output
        System.out.println("Hello World!");
    }
}

Output


Hello World!

Common Javadoc Tags

Here is a list of common Javadoc tags and their descriptions:

Tag	Description	Syntax
@author	Specifies the author of the class.	@author name
{@code}	Displays text in code font without interpreting it as HTML markup.	{@code text}
@param	Describes a parameter of a method.	@param parameter-name description
@return	Describes the return value of a method.	@return description
@throws	Describes the exceptions thrown by a method.	@throws exception-name description
@see	Creates a "See Also" link.	@see reference

Example - Using Javadoc Tags

Here’s an example of a more detailed Javadoc comment using several tags:

Java Source Code


import java.io.*;

/**
 * Add Two Numbers!
 * The AddNum program implements an application that
 * simply adds two given integer numbers and displays the
 * result.
 * 
 * Note: Proper comments make the code user-friendly and are considered a sign of quality.
 *
 * @author Zara Ali
 * @version 1.0
 * @since 2014-03-31
 */
public class AddNum {
    /**
     * Adds two integers.
     *
     * @param numA This is the first parameter to addNum method.
     * @param numB This is the second parameter to addNum method.
     * @return int This returns the sum of numA and numB.
     */
    public int addNum(int numA, int numB) {
        return numA + numB;
    }

    /**
     * This is the main method which makes use of addNum method.
     *
     * @param args Unused.
     * @throws IOException On input error.
     * @see IOException
     */
    public static void main(String args[]) throws IOException {
        AddNum obj = new AddNum();
        int sum = obj.addNum(10, 20);
        System.out.println("Sum of 10 and 20 is: " + sum);
    }
}

Output


Sum of 10 and 20 is: 30

Generating Javadoc Documentation

To generate the documentation for the AddNum class, run the following command:

Command


$ javadoc AddNum.java

This will generate an HTML file AddNum.html and an index.html file, where you can view the generated documentation.

Javadoc Using HTML5

To generate documentation in HTML5 format (Java 9 and above), use the -html5 option:

Command


$ javadoc -html5 AddNum.java

Generating the documentation in HTML5 format ensures modern styling and structure for the documentation output.