In this tutorial, we will learn how to write a Java Documentation (Java Doc or Javadoc) and the usage of JavaDoc tags.
1. Java Doc – Introduction
We can use any JavaDoc tool of their preference or the ALT + SHIFT + J key for generating a standard HTML documentation. In this tutorial, we will primarily focus on the keyboard keys but before going further let us take a deep dive at the Javadoc’s.
1.1 What is JavaDoc?
In software programming, JavaDoc is like multi-line comments but it contains some additional tags to prepare the HTML documentation of a class or a method.
- JavaDoc comments begin with
/**and ends with */ - It consists of a description which is followed by the block tags
- To generate the documentation, developers can write the following command in command line i.e.123
javadoc package_nameOR,javadoc file_name - As JavaDoc is generated in an HTML format, so that comments can include the HTML tags
- They are different from comments as comments allows a developer to comment out only one or multiple lines of code where JavaDoc offers a documentation comment support along with the tags
1.2 JavaDoc Tags
The following table lists the commonly used JavaDoc tags.
| Tags | Meaning | Used over? |
@see | Name of the associated class | Class, method |
@author | Author information such as name, email address, website, etc. | Class |
@version | Version information of a Class, Interface, or an Enum | Class |
@param | Constructor’s or Method’s input parameters information | Method |
@return | Information about the Return value of a method | Method |
@exception | Generated Exception in case of an invalid value | Method |
@throws | Generated Exception in case of an invalid value | Method |
@deprecated | Defines the element as deprecated/obsolete. Used by the compiler to generate the warnings | Class, Method |
@since | The API version in which this class, method, or a field was added | Class, Method |
To start with the captioned tutorial, we are hoping that users at present have their preferred Ide installed on their machines. For easy usage, I am using Eclipse Ide on a Windows operating system.
2. How to write Java Doc
We’ll demonstrate the use of commonly used JavaDoc tags in the software programming world. For a better understanding, developers can execute the below code in Eclipse Ide.
2.1 Example
Consider the following case that consists of two methods and their relevant JavaDoc.
Myclass.java
01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 | package com.jcg;/** * JavaDoc Example. * The class illustrates how to write comments used * to generate the JavaDoc documentation. * * @author yatinbatra * @version 1.2, 30 Dec 2019 */public class Myclass { /** * This method will print the received message on the console. * @param message String value to be printed * @since version 1.0 */ public void method1(final String message) { System.out.println("Message = " + message); } /** * The method will add the 2 numbers and return the result. * @param var1 The first value * @param var2 The second value * @return Sum between var1 and var2 * @since version 1.1 */ public int method2(final int var1, final int var2) { return var1 + var2; } /** * The method will add the 2 numbers and return the result. * @param var1 The first value * @param var2 The second value * @return Sum between var1 and var2 * @since version 1.2 * @throws Exception in case of an invalid value */ public int method3(final int var1, final int var2) throws Exception { return var1 + var2; }} |
Once done, developers can open the command-line terminal and run the following command (as shown in Fig. 1) to generate the HTML documentation inside the project’s package structure.
2.2 HTML Documentation
If everything goes well, the documentation (as shown in Fig. 2) will be successfully generated.
That is all for this tutorial and I hope the article served you with whatever you were looking for. Happy Learning and do not forget to share!
3. Summary
In this tutorial, we learned the usage of JavaDoc tags and how to generate HTML documentation using these tags. However, the usage of Java Documentation is purely up to the developer’s understand and implementation.
You can download the sample application as an Eclipse project in the Downloads section.
4. Download the Eclipse Project
This was an example of how to write a Java Documentation (Javadoc) in Java.
You can download the full source code of this example here: How to write Java Doc
The article is actually just a couple of sentences:
How to write Javadoc? The answer is simple – you don’t.
Whatever the arguments may follow, the answer is simple – you don’t.
Period. Use clear naming instead, consult Kevlin Henney if unsure how to do that.