The JavaDoc tool is a document generator tool that is used to generate standard documentation in HTML format. JavaDoc comes along with the Java Development Kit (JDK) and generates the API documentation for Java codes and provides information about classes, methods, fields, parameters and other elements of the Java codes.
Syntax for JavaDoc | JavaDoc comments
In Java, we can add comments to our application or program in following ways:
- Single-line comment
- Multi-line comment
- JavaDoc comment
public class CommentsExample {
// This is a Single-line comment
/*
* This is a Multi-line comment
*/
/**
* This is a JavaDoc comment
*/
}
Note: We can add as many comments as we want in our application; it does not affect the performance of our program because, at the time of compilation, comments are completely ignored by the Java compiler.
JavaDoc Tags
The Javadoc tags are the special annotations or directives used within Javadoc comments to provide specific information about the code elements being documented. These tags help in enhancing the clarity and completeness of the generated documentation.
| Tags | Parameter | Description |
| @author | author_name | Describe an author |
| @param | parameter | Provide the information about the method parameter |
| @see | reference | Generate a link to other element of the document |
| @version | version_name | Provide version of the class, interface |
| @return | description | Provide the return value |
JavaDoc Example
Below, we have an example of inter-thread communication. We have added the required comments to our banking class.
/**
* The Banking class simulates a simple banking system with basic deposit and withdraw operations.
* It uses synchronization to handle concurrent transactions and ensures thread-safe operations.
* If a withdrawal request exceeds the current balance, the withdrawing thread waits until a deposit is made.
*
* @author ankur.pal
*/
public class Banking {
/**
* The initial balance in the bank account.
*/
int balance = 1000;
/**
* Withdraws the specified amount from the account.
* If the balance is insufficient, the thread waits for a deposit to be made.
*
* @param amt the amount to withdraw
* @throws InterruptedException if the thread is interrupted while waiting
*/
public synchronized void withdraw(int amt) throws InterruptedException {
// If balance is less than the withdrawal amount, wait for a deposit
if (this.balance < amt) {
wait();
}
// Deduct the amount from the balance
this.balance -= amt;
System.out.println("Balance after withdrawal: " + this.balance);
}
/**
* Deposits the specified amount into the account and notifies all waiting threads.
*
* @param amt the amount to deposit
*/
public synchronized void deposit(int amt) {
// Add the amount to the balance
this.balance += amt;
// Notify waiting threads that a deposit has been made
notifyAll();
System.out.println("Balance after deposit: " + this.balance);
}
/**
* The main method simulates a concurrent banking scenario where one thread tries to withdraw
* an amount greater than the current balance, while another thread deposits an amount.
*
* @param args command-line arguments (not used)
*/
public static void main(String[] args) {
Banking banking = new Banking();
// Thread to perform a withdrawal of 1500
new Thread("withdraw-thread") {
public void run() {
try {
banking.withdraw(1500);
} catch (InterruptedException e) {
e.printStackTrace();
}
}
}.start();
// Thread to perform a deposit of 1000
new Thread("deposit-thread") {
public void run() {
banking.deposit(1000);
}
}.start();
}
}
How to generate JavaDoc in Intellij or Eclipse?
We can generate Javadoc using any IDE as it came integrated along with JDK. For this example, we will be using Eclipse. A similar process is there for Intellij IDE also.
Step 1: First, we need to go to Project and click on Generate Javadoc.
Step 2: As we click on Generate Javadoc, it will open a popup window where we are required to choose the project for which we want to generate API documentation and the destination where we want our documentation to be generated.
Step 3: As we click Finish, it will generate the API documentation in HTML format at the specified destination.
Step 4: Test
As we click Finish, it will generate the API document. We can go to the specified destination and can use the index.html page to visualize the complete documentation. We also navigate to CLASS, USE, TREE, and INDEX navigation to get complete details. documentation in HTML format at the specified destination.
Hello.
Good cheer to all on this beautiful day!!!!!
Good luck 🙂