Monday, September 24, 2018

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.

Related article


EmoticonEmoticon