Java 10 - Changes to Java documentation


In this blog post, We are going to learn the below changes to Javadoc in java 10

  • summary tag guide with examples
  • javadoc tool changes for supporting multiple stylesheets

java 10 - Javadoc summary tag

java 10 introduced many language changes. It also introduced java documentation changes - {@summary} tag

The summary tag provides a single line sentence to tell what exactly that method or API going to do. This can be applied to methods or classes. Currently, without a summary tag, Default is to place the content including period or dot and space at end of content.

Syntax

{@summary single line sentence}  

Example 

Here is an example of Summary Tag for below things 

How to generate the summary description of method and API classes

In the below example, 

Create and Update are documented with default summary content without a summary tag.

 Read and delete methods are documented with {@summary} tag

public class EmployeeAPI {  
 /**  
  * This method's create a Employee record in Database. Method do following  
  * things:  
  * <ul>  
  * <li>create Employee</li>  
  * <li>Insert into Database</li>  
  * <li>return void</li>  
  * </ul>  
  */  
 public void create() {  
  
 }  
  
 /**  
  * This method's update a Employee record in Database. Method do following  
  * things:  
  * <ul>  
  * <li>update Employee</li>  
  * <li>Update Employee in Database</li>  
  * <li>return void</li>  
  * </ul>  
  */  
 public void update() {  
  
 }  
  
 /**  
  * {@summary This method's read a Employee record in Database. Method do  
  * following things:  
  * <ul>  
  * <li>Read Employee</li>  
  * <li>Read Employee from Database</li>  
  * <li>return void</li>  
  * </ul>  
  * }  
  */  
 public void read() {  
  
 }  
  
 /**  
  * {@summary This method's delete a Employee record in Database. Method do  
  * following things:  
  * <ul>  
  * <li>delete Employee</li>  
  * <li>Delete Employee in Database</li>  
  * <li>return void</li>  
  * </ul>  
  * }  
  */  
 public void delete() {  
  
 }  
}  

Using javadoc tool, Generated the java documentation for the above code

B:\Workspace\cloudhadoop\src>java --version  
java 10.0.2 2018-07-17  
Java(TM) SE Runtime Environment 18.3 (build 10.0.2+13)  
Java HotSpot(TM) 64-Bit Server VM 18.3 (build 10.0.2+13, mixed mode)  
  
B:\Workspace\cloudhadoop\src>javac --version  
javac 10.0.2  
B:\Workspace\cloudhadoop\src>javadoc EmployeeAPI.java  
Loading source file EmployeeAPI.java...  
Constructing Javadoc information...  
javadoc: warning - You have not specified the version of HTML to use.  
The default is currently HTML 4.01, but this will change to HTML5  
in a future release. To suppress this warning, please specify the  
version of HTML used in your documentation comments and to be  
generated by this doclet, using the -html4 or -html5 options.  
Standard Doclet version 10.0.2  
Building tree for all the packages and classes...  
Generating .\EmployeeAPI.html...  
Generating .\package-frame.html...  
Generating .\package-summary.html...  
Generating .\package-tree.html...  
Generating .\constant-values.html...  
Building index for all the packages and classes...  
Generating .\overview-tree.html...  
Generating .\index-all.html...  
Generating .\deprecated-list.html...  
Building index for all classes...  
Generating .\allclasses-frame.html...  
Generating .\allclasses-frame.html...  
Generating .\allclasses-noframe.html...  
Generating .\allclasses-noframe.html...  
Generating .\index.html...  
Generating .\help-doc.html...  

Output of the above Javadoc tool is HTML file as below

java10 summary tag

javadoc tool changes for supporting multiple stylesheets 

Documentation of java code is generated using below two options Using maven command

mvn javadoc:javadoc  

javadoc is maven goal for generating java documentation for maven java project and output is HTML file Using Javadoc tool Javadoc is a command line tool to generate java documentation WIth java 10, Javadoc support multiple stylesheets using -add-stylesheets as below

 Javadoc --add-stylesheet 

This generates HTML output file with given applied.

Similar Posts