Proper documentation plays a vital role for any software. It not only guides how to use software and its features but also proves to be useful for other software developers to understand its code and its workings. Good documentation always leads to smooth adaptation and maintenance of software. Like other countless features, Java provides a tool for documentation of Java programs called Javadoc which is used to generate documentation in an HTML page format.
Table of Contents
In this article, we will be discussing how it works with the help of some examples and how we can make use of it to generate useful documentation for Java code.
JavaDoc tool is a document generator tool offered in Java. It comes with JDK and is used to generate API documentation in HTML format from a Java source code. It uses the “doc comments” format for documenting the Java classes. Now, numerous Java IDEs like Eclipse, IntelliJ IDEA and Netbeans can also generate an HTML document automatically using the Javadoc features.
Along with documentation, it also provides an API for creating dockets and taglets, that allows developers to further analyze the structure of a Java application. It parses the declarations ad documentation in a set of the source file that includes the description of classes, methods, constructors, and fields used in the code.
Just like in any other programing language, comments are very commonly used in Java to explain the working of a code. There are three types of comments in Java.
1. Single Line Comments that contain text. It starts with “//” and spans an entire line as shown below,
//This is a single-line text comment.
2. Multi-Line Comments also contains text but it spans over multiple lines. It starts with “/*” and ends with “*/” like this,
/* This is a multi-line texts comment */
3. Javadoc Comments contains documentation also known as “doc comment”. These are used by the Javadoc tool for preparing the automatically generated documentation. It starts with “/**” and ends with “*/”. See this example,
/** * <h1>My Program</h1> * @author Shaharyar Lalani * @version 1.1 * @since 2022-06-11 */
The Javadoc comments are used by the it’s tool to generate the documentation API for the code. You must have noticed an extra asterisk in the format of its comments. It is not a typing mistake, the format for its comments is different from the normal comments as it may also contain the HTML tags as shown in the example which is not the case with normal comments in Java.
A Javadoc comment is divided into two parts. First, it contains the description of the code including the information about classes, methods, constructors, etc. in separate lines and then the Java doc tags (starting with @) for specific meta-data. These comments are always placed at the very start of the Java code, before the class, field, or methods. Java doc comments do not have any effect on the performance of a Java application as just like any other comments, they are cleared out in the compilation process.
Javadoc tags are used in its comments to specify the metadata about the Java code. The metadata gives more meaning to a code making it more understandable and easier to maintain. Java doc tag always begins with the “@” symbol. There is a list of tags defined in Javadoc that are used for various purposes.
Following are some of the most commonly used Javadoc tags along with their parameters and description.
Javadoc also allows the creation of custom tags according to the requirement of the code. You can create Javadoc tags to make your document more user-friendly.The following Javadoc command is used to create custom tags.
@docRoot
The @throws tag also does the same thing.
Javadoc also allows the creation of custom tags according to the requirement of the code. You can create Javadoc tags to make your document more user-friendly. The following Javadoc command is used to create custom tags.
javadoc -tag <tag-name>:<location:allowed>:<text-name-in-output> <class-location>
The creation of a Javadoc API does not require you to compile the java code. You just need to use a Javadoc command. You have to first specify the class or the package for which you want to create the documentation then by using the -d flag you can specify the location where you want to create the documentation. See this statement below,
javadoc -d doc <class or package name>
Upon execution, the above-mentioned statement will create multiple HTML files containing all the information about the package, classes, hierarchy etc.
The following Java code demonstrates the use of various Javadoc tags and comments. The documentation about the following class will be produced in an HTML file called calcProduct.html along with a master file with the name “index.html” at the specified location.
1. import java.io.*; 2. 3. /** 4. * <h1>Find the Product of two numbers</h1> 5. * This program multiplies two integer values and outputs their product. 6. * <p> 7. * 8. * @author Shaharyar Lalani 9. * @version 1.0 10. * @since 2022-07-10 11. */ 12. public class calcProduct { 13. /** 14. * This method is used to find the product of two integers. This is a simple class method, 15. * demonstrating the use of some Java doc Tags. 16. * @param number1 This is the first parameter to the calcProduct method. 17. * @param number2 This is the second parameter to the calcProduct method. 18. * @return int It will return the product of both parameters in integer. 19. */ 20. public int calcProduct (int number1, int number2) { 21. return number1 * number2; 22. } 23. 24. /** 25. * This is the main method which makes use of the calcProduct method. 26. * @param args Unused. 27. * @return Nothing. 28. * @throws IOException on input error. 29. * @see IOException 30. */ 31. 32. public static void main(String args[]) throws IOException { 33. calcProduct obj1 = new calcProduct(); 34. int product = obj1. calcProduct(7, 3); 35. 36. System.out.println("Product of 7 and 3 :" + product); 37. } 38. } 39.
The table below demonstrates the class information from the generated Javadoc HTML file from the code mentioned above,
Javadoc is a documentation generator tool in Java, used to generate documentation for the Java code. We discussed the use of Javadoc comments and tags in the source code to create descriptive and easy-to-understand documentation. It also allows you to create custom Javadoc tags as per your requirements. Javadoc is a remarkable tool as the generated document offers various features like it makes the code easy to maintain and it makes it very easy for developers to work on someone else’s code.
Also Read: An Introduction to Domain-Driven Design In Java
Full Stack Java Developer | Writer | Recruiter, bridging the gap between exceptional talent and opportunities, for some of the biggest Fortune 500 companies.
Create a free profile and find your next great opportunity.
Sign up and find a perfect match for your team.
Xperti vets skilled professionals with its unique talent-matching process.
Connect and engage with technology enthusiasts.
© Xperti.io All Rights Reserved
Privacy
Terms of use