Java 10 documentation changes | summary tag

Java 10 documentation changes | summary tag

Learn the below changes to Javadoc in the java 10 version.

  • 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 the content.

Syntax

{@summary single line sentence}

java10 summary tag Example

Here is an example of Summary Tag for below things

How to generate the summary description of the method and API classes?

In the below example,

  • Created four methods - Create, Update, Read, and methods.
  • Create and Update are documented with default summary content without a summary tag.
  • Read and delete methods are documented with {@summary} tag

Here is an example for 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
a 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...

The output of the above Javadoc tool is HTML file as below

java10 summary tag generation

Javadoc tool changes for supporting multiple stylesheets

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

Here is maven command

mvn javadoc:javadoc

javadoc is maven’s goal for generating java documentation for the 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

It generates an HTML output file with the given applied stylesheet.