JDK 10的摘要Javadoc标签

JDK 10通过发行JDK-8173425 引入了Javadoc标签{@summary} （“ Javadoc需要一个新标签来指定摘要。”）。 这个新标签允许开发人员显式指定Javadoc注释的哪些部分出现在“摘要”中，而不是依靠Javadoc的默认处理来寻找一个时间和空间来划定注释的摘要部分的结尾。 JDK-8173425指出：“当前在javadoc中，元素的摘要（第一句）由点空间规则或需要时使用BreakIterator解密。” 它补充说，知道隐式选择的摘要句子将是什么可能会令人困惑。

查看{@summary}的最简单方法可能是通过Javadoc示例。 下一个代码清单显示了四种具有类似Javadoc注释的方法，两种使用显式的{@summary}标记，两种依赖于隐式的Javadoc摘要构造。

在Javadoc方法注释中展示{@summary}

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()
   {
   }
}

当针对此简单类执行第一个JDK 10（18.3）Release Candidate（内部版本43）附带的Javadoc工具时，在Web浏览器中生成HTML的“ Method Summary ”部分如下所示。

将HTML输出与上面的注释Java代码进行比较，演示了{@summary}如何允许对方法摘要中出现的内容进行显式控制。

翻译自: https://www.javacodegeeks.com/2018/02/jdk-10s-summary-javadoc-tag.html