Java 10 documentation changes | summary tag
Learn about the changes to Javadoc in Java 10, including the summary tag guide with examples and Javadoc tool changes to support multiple stylesheets.
Java 10 Javadoc Summary Tag
Java 10 introduced several language changes, including changes to Java documentation with the {@summary} tag.
The summary tag provides a single-line sentence to describe what a method or API does. It can be applied to methods or classes. By default, without a summary tag, the content ends with a period or dot and a space.
Syntax
{@summary single line sentence}Java 10 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 the Javadoc tool, generate 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
Javadoc Tool Changes for Supporting Multiple Stylesheets
Java code documentation can be generated using either the Maven command or the Javadoc command.
Here is maven command
mvn javadoc:javadocThe javadoc goal in Maven generates Java documentation for the Maven Java project, and the output is an HTML file.
Using Javadoc tool:
Javadoc is a command-line tool to generate Java documentation. With Java 10, Javadoc supports multiple stylesheets using the -add option.
Javadoc --add-stylesheetThis generates an HTML output file with the specified applied stylesheet.
