Home » Core Java » How to write Java Doc

About Yatin

Yatin
The author is graduated in Electronics & Telecommunication. During his studies, he has been involved with a significant number of projects ranging from programming and software engineering to telecommunications analysis. He works as a technical lead in the information technology sector where he is primarily involved with projects based on Java/J2EE technologies platform and novel UI technologies.

How to write Java Doc

Hello readers, in this tutorial, we will learn how to write a Java Doc in Java programming language.

1. Introduction

In Java programming, developers 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.
    1
    2
    3
    javadoc package_name
    OR,
    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.

TagsMeaningUsed over?
@seeName of the associated classClass, method
@authorAuthor information such as name, email address, website, etc.Class
@versionVersion information of a Class, Interface, or an EnumClass
@paramConstructor’s or Method’s input parameters informationMethod
@returnInformation about the Return value of a methodMethod
@exceptionGenerated Exception in case of an invalid valueMethod
@throwsGenerated Exception in case of an invalid valueMethod
@deprecatedDefines the element as deprecated/obsolete. Used by the compiler to generate the warningsClass, Method
@sinceThe API version in which this class, method, or a field was addedClass, 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.

Java Doc - command
Fig. 1: JavaDoc command

2.2 HTML Documentation

If everything goes well, the documentation (as shown in Fig. 2) will be successfully generated.

Java Doc - Generated HTML documentation
Fig. 2: Generated HTML documentation

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. Conclusion

In this tutorial, we learned the usage of JavaDoc tags and how to generate HTML documentation using these tags. However, the usage of JavaDoc is purely up to the developer’s understand and implementation. Developers can download the sample application as an Eclipse project in the Downloads section.

4. Download the Eclipse Project

This was an example of JavaDoc in the Java programming language.

Download
You can download the full source code of this example here: How to write Java Doc
(No Ratings Yet)
1 Comment Views Tweet it!

Do you want to know how to develop your skillset to become a Java Rockstar?

Subscribe to our newsletter to start Rocking right now!

To get you started we give you our best selling eBooks for FREE!

 

1. JPA Mini Book

2. JVM Troubleshooting Guide

3. JUnit Tutorial for Unit Testing

4. Java Annotations Tutorial

5. Java Interview Questions

6. Spring Interview Questions

7. Android UI Design

 

and many more ....

 

Receive Java & Developer job alerts in your Area

 

1
Leave a Reply

avatar
1 Comment threads
0 Thread replies
0 Followers
 
Most reacted comment
Hottest comment thread
1 Comment authors
Upset dev Recent comment authors
  Subscribe  
newest oldest most voted
Notify of
Upset dev
Guest
Upset dev

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.