JDK 10 introduces a Javadoc tag {@summary} via issue JDK-8173425 (“Javadoc needs a new tag to specify the summary.”). This new tag allows the developer to explicitly specify what portion of the Javadoc comment appears in the “summary” rather than relying on Javadoc’s default treatment looking for a period and space to demarcate the end of the summary portion of the comment. JDK-8173425 states, “Currently in javadoc the summary (firstsentence) of an element is deciphered by a dot-space rule, or if required using BreakIterator.” It adds that it can be confusing to know what that implicitly selected summary sentence will be.
The easiest way to see {@summary} in action may be through Javadoc examples. The next code listing shows four methods with similar Javadoc comments, two using explicit {@summary} tags and two relying on implicit Javadoc summary construction.
Demonstrating {@summary} in Javadoc Method Comments
package dustin.examples.javadoc;
/**
* Demonstrate JDK 10 added summary support. Demonstrates
* this by comparing similar methods' Javadoc comments with
* and without use of new "@summary" tag.
*/
public class Summary
{
/**
* This method's first sentence is normally in the summary.
* Here are some of its characteristics:
* <ul>
* <li>This method does great things.</li>
* <li>This method does not really do anything.</li>
* </ul>
*/
public void implicitSummary1()
{
}
/**
* This method's first sentence is normally in the summary.Here are some of its characteristics:
* <ul>
* <li>This method does great things.</li>
* <li>This method does not really do anything.</li>
* </ul>
*/
public void implicitSummary2()
{
}
/**
* {@summary This method's first sentence is normally in the summary.
* Here are some of its characteristics:
* <ul>
* <li>This method does great things.</li>
* <li>This method does not really do anything.</li>
* </ul>}
*/
public void explicitSummary1()
{
}
/**
* {@summary This method's first sentence is normally in the summary.Here are some of its characteristics:
* <ul>
* <li>This method does great things.</li>
* <li>This method does not really do anything.</li>
* </ul>}
*/
public void explicitSummary2()
{
}
}When the Javadoc tool delivered with the first JDK 10 (18.3) Release Candidate (Build 43) is executed against this simple class, the “Method Summary” section of the generated HTML appears as follows in a web browser.
Comparing the HTML output to the commented Java code above it demonstrates how the {@summary} allows for explicit control of what appears in the methods’ summaries.
| Published on Java Code Geeks with permission by Dustin Marx, partner at our JCG program. See the original article here: JDK 10’s Summary Javadoc Tag Opinions expressed by Java Code Geeks contributors are their own. |
