Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

JDK 10's Summary Javadoc Tag

DZone's Guide to

JDK 10's Summary Javadoc Tag

Among the improvements coming in Java 10 is the summary Javadoc tag. See its intention and how it works to bring some clarity to your code.

· Java Zone ·
Free Resource

Verify, standardize, and correct the Big 4 + more– name, email, phone and global addresses – try our Data Quality APIs now at Melissa Developer Portal!

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.

Developers! Quickly and easily gain access to the tools and information you need! Explore, test and combine our data quality APIs at Melissa Developer Portal – home to tools that save time and boost revenue. Our APIs verify, standardize, and correct the Big 4 + more – name, email, phone and global addresses – to ensure accurate delivery, prevent blacklisting and identify risks in real-time.

Topics:
java ,javadoc ,summary ,tutorial

Published at DZone with permission of

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}