changeset 46184:f1325703ea85

8173425: Javadoc needs a new tag to specify the summary. Reviewed-by: jjg
author ksrini
date Tue, 15 Aug 2017 13:16:32 -0700
parents 5091e36e106b
children f4c981fc7818
files langtools/src/jdk.compiler/share/classes/com/sun/source/doctree/DocTree.java langtools/src/jdk.compiler/share/classes/com/sun/source/doctree/DocTreeVisitor.java langtools/src/jdk.compiler/share/classes/com/sun/source/doctree/SummaryTree.java langtools/src/jdk.compiler/share/classes/com/sun/source/util/DocTreeFactory.java langtools/src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java langtools/src/jdk.compiler/share/classes/com/sun/source/util/SimpleDocTreeVisitor.java langtools/src/jdk.compiler/share/classes/com/sun/tools/doclint/Checker.java langtools/src/jdk.compiler/share/classes/com/sun/tools/doclint/resources/doclint.properties langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DCTree.java langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DocPretty.java langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DocTreeMaker.java langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SummaryTaglet.java langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletManager.java langtools/test/jdk/javadoc/doclet/testSummaryTag/TestSummaryTag.java langtools/test/jdk/javadoc/doclet/testSummaryTag/p1/A.java langtools/test/jdk/javadoc/doclet/testSummaryTag/p1/B.java langtools/test/jdk/javadoc/doclet/testSummaryTag/p1/package.html langtools/test/jdk/javadoc/doclet/testSummaryTag/p2/A.java langtools/test/jdk/javadoc/doclet/testSummaryTag/p2/package.html langtools/test/jdk/javadoc/doclet/testSummaryTag/p3/A.java langtools/test/jdk/javadoc/doclet/testSummaryTag/p3/overview.html langtools/test/tools/doclint/SummaryTest.java langtools/test/tools/doclint/SummaryTest.out langtools/test/tools/javac/completionDeps/DepsAndDocLint.java langtools/test/tools/javac/doctree/DocCommentTester.java langtools/test/tools/javac/doctree/SummaryTest.java langtools/test/tools/javac/lib/DPrinter.java
diffstat 29 files changed, 767 insertions(+), 13 deletions(-) [+]
line wrap: on
line diff
--- a/langtools/src/jdk.compiler/share/classes/com/sun/source/doctree/DocTree.java	Tue Aug 08 23:00:45 2017 +0000
+++ b/langtools/src/jdk.compiler/share/classes/com/sun/source/doctree/DocTree.java	Tue Aug 15 13:16:32 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -205,6 +205,12 @@
         START_ELEMENT,
 
         /**
+         * Used for instances of {@link SummaryTree}
+         * representing the summary of a comment description.
+         */
+        SUMMARY("summary"),
+
+        /**
          * Used for instances of {@link TextTree}
          * representing some documentation text.
          */
--- a/langtools/src/jdk.compiler/share/classes/com/sun/source/doctree/DocTreeVisitor.java	Tue Aug 08 23:00:45 2017 +0000
+++ b/langtools/src/jdk.compiler/share/classes/com/sun/source/doctree/DocTreeVisitor.java	Tue Aug 15 13:16:32 2017 -0700
@@ -257,6 +257,19 @@
     R visitStartElement(StartElementTree node, P p);
 
     /**
+     * Visits a SummaryTree node.
+     *
+     * @implSpec Visits a {@code SummaryTree} node
+     * by calling {@code visitOther(node, p)}.
+     *
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     * @since 10
+     */
+    default R visitSummary(SummaryTree node, P p) { return visitOther(node, p);}
+
+    /**
      * Visits a TextTree node.
      * @param node the node being visited
      * @param p a parameter value
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/langtools/src/jdk.compiler/share/classes/com/sun/source/doctree/SummaryTree.java	Tue Aug 15 13:16:32 2017 -0700
@@ -0,0 +1,44 @@
+/*
+ * Copyright (c) 2017, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+package com.sun.source.doctree;
+
+import java.util.List;
+
+/**
+ * A tree node for an @summary inline tag.
+ *
+ * <p>
+ * {&#064;summary text}
+ *
+ * @since 10
+ */
+public interface SummaryTree extends InlineTagTree {
+    /**
+     * Returns the summary or the first line of a comment.
+     * @return the summary text
+     */
+    List<? extends DocTree> getSummary();
+}
--- a/langtools/src/jdk.compiler/share/classes/com/sun/source/util/DocTreeFactory.java	Tue Aug 08 23:00:45 2017 +0000
+++ b/langtools/src/jdk.compiler/share/classes/com/sun/source/util/DocTreeFactory.java	Tue Aug 15 13:16:32 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -58,6 +58,7 @@
 import com.sun.source.doctree.SerialTree;
 import com.sun.source.doctree.SinceTree;
 import com.sun.source.doctree.StartElementTree;
+import com.sun.source.doctree.SummaryTree;
 import com.sun.source.doctree.TextTree;
 import com.sun.source.doctree.ThrowsTree;
 import com.sun.source.doctree.UnknownBlockTagTree;
@@ -288,6 +289,19 @@
     StartElementTree newStartElementTree(Name name, List<? extends DocTree> attrs, boolean selfClosing);
 
     /**
+     * Create a new {@code SummaryTree} object, to represent a {@code @summary } tag.
+     *
+     * @implSpec This implementation throws {@code UnsupportedOperationException}.
+     *
+     * @param summary the content of the tag
+     * @return a {@code SummaryTree} object
+     * @since 10
+     */
+    default SummaryTree newSummaryTree(List<? extends DocTree> summary) {
+        throw new UnsupportedOperationException("not implemented");
+    }
+
+    /**
      * Create a new {@code TextTree} object, to represent some plain text.
      * @param text the text
      * @return a {@code TextTree} object
--- a/langtools/src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java	Tue Aug 08 23:00:45 2017 +0000
+++ b/langtools/src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java	Tue Aug 15 13:16:32 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -438,6 +438,20 @@
     }
 
     /**
+     * {@inheritDoc} This implementation scans the children in left to right order.
+     *
+     * @param node  {@inheritDoc}
+     * @param p  {@inheritDoc}
+     * @return the result of scanning
+     * @since 10
+     */
+    @Override
+    public R visitSummary(SummaryTree node, P p) {
+        R r = scan(node.getSummary(), p);
+        return r;
+    }
+
+    /**
      * {@inheritDoc} This implementation returns {@code null}.
      *
      * @param node  {@inheritDoc}
--- a/langtools/src/jdk.compiler/share/classes/com/sun/source/util/SimpleDocTreeVisitor.java	Tue Aug 08 23:00:45 2017 +0000
+++ b/langtools/src/jdk.compiler/share/classes/com/sun/source/util/SimpleDocTreeVisitor.java	Tue Aug 15 13:16:32 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -401,6 +401,19 @@
      * @param node {@inheritDoc}
      * @param p {@inheritDoc}
      * @return  the result of {@code defaultAction}
+     * @since 10
+     */
+    @Override
+    public R visitSummary(SummaryTree node, P p) {
+        return defaultAction(node, p);
+    }
+
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
      */
     @Override
     public R visitText(TextTree node, P p) {
--- a/langtools/src/jdk.compiler/share/classes/com/sun/tools/doclint/Checker.java	Tue Aug 08 23:00:45 2017 +0000
+++ b/langtools/src/jdk.compiler/share/classes/com/sun/tools/doclint/Checker.java	Tue Aug 15 13:16:32 2017 -0700
@@ -70,6 +70,7 @@
 import com.sun.source.doctree.SerialFieldTree;
 import com.sun.source.doctree.SinceTree;
 import com.sun.source.doctree.StartElementTree;
+import com.sun.source.doctree.SummaryTree;
 import com.sun.source.doctree.TextTree;
 import com.sun.source.doctree.ThrowsTree;
 import com.sun.source.doctree.UnknownBlockTagTree;
@@ -107,6 +108,7 @@
     Map<Element, Set<String>> foundAnchors = new HashMap<>();
     boolean foundInheritDoc = false;
     boolean foundReturn = false;
+    boolean hasNonWhitespaceText = false;
 
     public enum Flag {
         TABLE_HAS_CAPTION,
@@ -189,6 +191,7 @@
         foundThrows.clear();
         foundInheritDoc = false;
         foundReturn = false;
+        hasNonWhitespaceText = false;
 
         scan(new DocTreePath(p, tree), null);
 
@@ -245,7 +248,8 @@
 
     @Override @DefinedBy(Api.COMPILER_TREE)
     public Void visitText(TextTree tree, Void ignore) {
-        if (hasNonWhitespace(tree)) {
+        hasNonWhitespaceText = hasNonWhitespace(tree);
+        if (hasNonWhitespaceText) {
             checkAllowsText(tree);
             markEnclosingTag(Flag.HAS_TEXT);
         }
@@ -906,6 +910,17 @@
     }
 
     @Override @DefinedBy(Api.COMPILER_TREE)
+    public Void visitSummary(SummaryTree node, Void aVoid) {
+        int idx = env.currDocComment.getFullBody().indexOf(node);
+        // Warn if the node is preceded by non-whitespace characters,
+        // or other non-text nodes.
+        if ((idx == 1 && hasNonWhitespaceText) || idx > 1) {
+            env.messages.warning(SYNTAX, node, "dc.invalid.summary", node.getTagName());
+        }
+        return super.visitSummary(node, aVoid);
+    }
+
+    @Override @DefinedBy(Api.COMPILER_TREE)
     public Void visitThrows(ThrowsTree tree, Void ignore) {
         ReferenceTree exName = tree.getExceptionName();
         Element ex = env.trees.getElement(new DocTreePath(getCurrentPath(), exName));
@@ -1091,6 +1106,7 @@
     boolean hasNonWhitespace(TextTree tree) {
         String s = tree.getBody();
         for (int i = 0; i < s.length(); i++) {
+            Character c = s.charAt(i);
             if (!Character.isWhitespace(s.charAt(i)))
                 return true;
         }
--- a/langtools/src/jdk.compiler/share/classes/com/sun/tools/doclint/resources/doclint.properties	Tue Aug 08 23:00:45 2017 +0000
+++ b/langtools/src/jdk.compiler/share/classes/com/sun/tools/doclint/resources/doclint.properties	Tue Aug 15 13:16:32 2017 -0700
@@ -45,6 +45,7 @@
 dc.invalid.param = invalid use of @param
 dc.invalid.provides = invalid use of @provides
 dc.invalid.return = invalid use of @return
+dc.invalid.summary = invalid use of @summary
 dc.invalid.throws = invalid use of @throws
 dc.invalid.uses = invalid use of @uses
 dc.invalid.uri = invalid uri: "{0}"
--- a/langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java	Tue Aug 08 23:00:45 2017 +0000
+++ b/langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java	Tue Aug 15 13:16:32 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -1260,6 +1260,14 @@
                 }
             },
 
+            // @summary summary-text
+            new TagParser(Kind.INLINE, DCTree.Kind.SUMMARY) {
+                public DCTree parse(int pos) throws ParseException {
+                    List<DCTree> summary = inlineContent();
+                    return m.at(pos).newSummaryTree(summary);
+                }
+            },
+
             // @throws class-name description
             new TagParser(Kind.BLOCK, DCTree.Kind.THROWS) {
                 public DCTree parse(int pos) throws ParseException {
--- a/langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DCTree.java	Tue Aug 08 23:00:45 2017 +0000
+++ b/langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DCTree.java	Tue Aug 15 13:16:32 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -826,6 +826,29 @@
         }
     }
 
+    public static class DCSummary extends DCInlineTag implements SummaryTree {
+        public final List<DCTree> summary;
+
+        DCSummary(List<DCTree> summary) {
+            this.summary = summary;
+        }
+
+        @Override @DefinedBy(Api.COMPILER_TREE)
+        public Kind getKind() {
+            return Kind.SUMMARY;
+        }
+
+        @Override @DefinedBy(Api.COMPILER_TREE)
+        public <R, D> R accept(DocTreeVisitor<R, D> v, D d) {
+            return v.visitSummary(this, d);
+        }
+
+        @Override @DefinedBy(Api.COMPILER_TREE)
+        public List<? extends DocTree> getSummary() {
+            return summary;
+        }
+    }
+
     public static class DCText extends DCTree implements TextTree {
         public final String text;
 
--- a/langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DocPretty.java	Tue Aug 08 23:00:45 2017 +0000
+++ b/langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DocPretty.java	Tue Aug 15 13:16:32 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -503,6 +503,22 @@
     }
 
     @Override @DefinedBy(Api.COMPILER_TREE)
+    public Void visitSummary(SummaryTree node, Void p) {
+        try {
+            print("{");
+            printTagName(node);
+            if (!node.getSummary().isEmpty()) {
+                print(" ");
+                print(node.getSummary());
+            }
+            print("}");
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+        return null;
+    }
+
+    @Override @DefinedBy(Api.COMPILER_TREE)
     public Void visitText(TextTree node, Void p) {
         try {
             print(node.getBody());
--- a/langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DocTreeMaker.java	Tue Aug 08 23:00:45 2017 +0000
+++ b/langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DocTreeMaker.java	Tue Aug 15 13:16:32 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -78,6 +78,7 @@
 import com.sun.tools.javac.tree.DCTree.DCSerialField;
 import com.sun.tools.javac.tree.DCTree.DCSince;
 import com.sun.tools.javac.tree.DCTree.DCStartElement;
+import com.sun.tools.javac.tree.DCTree.DCSummary;
 import com.sun.tools.javac.tree.DCTree.DCText;
 import com.sun.tools.javac.tree.DCTree.DCThrows;
 import com.sun.tools.javac.tree.DCTree.DCUnknownBlockTag;
@@ -412,6 +413,13 @@
     }
 
     @Override @DefinedBy(Api.COMPILER_TREE)
+    public DCSummary newSummaryTree(List<? extends DocTree> text) {
+        DCSummary tree = new DCSummary(cast(text));
+        tree.pos = pos;
+        return tree;
+    }
+
+    @Override @DefinedBy(Api.COMPILER_TREE)
     public DCText newTextTree(String text) {
         DCText tree = new DCText(text);
         tree.pos = pos;
@@ -497,6 +505,9 @@
                     continue;
                 }
                 switch (dt.getKind()) {
+                    case SUMMARY:
+                        foundFirstSentence = true;
+                        break;
                     case TEXT:
                         DCText tt = (DCText) dt;
                         String s = tt.getBody();
--- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java	Tue Aug 08 23:00:45 2017 +0000
+++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java	Tue Aug 15 13:16:32 2017 -0700
@@ -60,6 +60,7 @@
 import com.sun.source.doctree.LiteralTree;
 import com.sun.source.doctree.SeeTree;
 import com.sun.source.doctree.StartElementTree;
+import com.sun.source.doctree.SummaryTree;
 import com.sun.source.doctree.TextTree;
 import com.sun.source.util.SimpleDocTreeVisitor;
 
@@ -1980,6 +1981,15 @@
                     return false;
                 }
 
+                @Override
+                public Boolean visitSummary(SummaryTree node, Content c) {
+                    Content output = TagletWriter.getInlineTagOutput(element,
+                            configuration.tagletManager, holderTag, tag,
+                            getTagletWriterInstance(isFirstSentence));
+                    result.addContent(output);
+                    return false;
+                }
+
                 private CharSequence textCleanup(String text, boolean isLast) {
                     return textCleanup(text, isLast, false);
                 }
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SummaryTaglet.java	Tue Aug 15 13:16:32 2017 -0700
@@ -0,0 +1,57 @@
+/*
+ * Copyright (c) 2017, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+package jdk.javadoc.internal.doclets.toolkit.taglets;
+
+import javax.lang.model.element.Element;
+
+import com.sun.source.doctree.DocTree;
+import com.sun.source.doctree.SummaryTree;
+import jdk.javadoc.internal.doclets.toolkit.Content;
+
+import static com.sun.source.doctree.DocTree.Kind.*;
+
+/**
+ * A taglet that represents the @summary tag.
+ *
+ *  <p><b>This is NOT part of any supported API.
+ *  If you write code that depends on this, you do so at your own risk.
+ *  This code and its internal interfaces are subject to change or
+ *  deletion without notice.</b>
+ */
+
+public class SummaryTaglet extends BaseInlineTaglet {
+
+    public SummaryTaglet() {
+        name = SUMMARY.tagName;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public Content getTagletOutput(Element holder, DocTree tag, TagletWriter writer) {
+        return writer.commentTagsToOutput(holder, ((SummaryTree)tag).getSummary());
+    }
+}
--- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletManager.java	Tue Aug 08 23:00:45 2017 +0000
+++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletManager.java	Tue Aug 15 13:16:32 2017 -0700
@@ -726,6 +726,7 @@
         addStandardTaglet(new LiteralTaglet());
         addStandardTaglet(new CodeTaglet());
         addStandardTaglet(new IndexTaglet());
+        addStandardTaglet(new SummaryTaglet());
 
         // Keep track of the names of standard tags for error
         // checking purposes. The following are not handled above.
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/langtools/test/jdk/javadoc/doclet/testSummaryTag/TestSummaryTag.java	Tue Aug 15 13:16:32 2017 -0700
@@ -0,0 +1,123 @@
+/*
+ * Copyright (c) 2017, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/*
+ * @test
+ * @bug      8173425
+ * @summary  tests for the summary tag behavior
+ * @library  ../lib
+ * @modules jdk.javadoc/jdk.javadoc.internal.tool
+ * @build    JavadocTester
+ * @run main TestSummaryTag
+ */
+
+public class TestSummaryTag extends JavadocTester {
+
+    public static void main(String... args) throws Exception {
+        TestSummaryTag tester = new TestSummaryTag();
+        tester.runTests();
+    }
+
+    @Test
+    void test1() {
+        javadoc("-d", "out1",
+                "-sourcepath", testSrc,
+                "p1");
+        checkExit(Exit.OK);
+
+        checkOutput("index-all.html", true,
+            "<dl>\n"
+            + "<dt><span class=\"memberNameLink\"><a href=\"p1/A.html#m--\">m()"
+            + "</a></span> - Method in class p1.<a href=\"p1/A.html\" title=\"class in p1\">A</a></dt>\n"
+            + "<dd>\n"
+            + "<div class=\"block\">First sentence</div>\n"
+            + "</dd>\n"
+            + "<dt><span class=\"memberNameLink\"><a href=\"p1/B.html#m--\">m()"
+            + "</a></span> - Method in class p1.<a href=\"p1/B.html\" title=\"class in p1\">B</a></dt>\n"
+            + "<dd>\n"
+            + "<div class=\"block\">First sentence</div>\n"
+            + "</dd>\n"
+            + "<dt><span class=\"memberNameLink\"><a href=\"p1/A.html#m1--\">m1()"
+            + "</a></span> - Method in class p1.<a href=\"p1/A.html\" title=\"class in p1\">A</a></dt>\n"
+            + "<dd>\n"
+            + "<div class=\"block\"> First sentence </div>\n"
+            + "</dd>\n"
+            + "<dt><span class=\"memberNameLink\"><a href=\"p1/A.html#m2--\">m2()"
+            + "</a></span> - Method in class p1.<a href=\"p1/A.html\" title=\"class in p1\">A</a></dt>\n"
+            + "<dd>\n"
+            + "<div class=\"block\">Some html &lt;foo&gt; &nbsp; codes</div>\n"
+            + "</dd>\n"
+            + "<dt><span class=\"memberNameLink\"><a href=\"p1/A.html#m3--\">m3()"
+            + "</a></span> - Method in class p1.<a href=\"p1/A.html\" title=\"class in p1\">A</a></dt>\n"
+            + "<dd>\n"
+            + "<div class=\"block\">First sentence </div>\n"
+            + "</dd>\n"
+            + "<dt><span class=\"memberNameLink\"><a href=\"p1/A.html#m4--\">m4()"
+            + "</a></span> - Method in class p1.<a href=\"p1/A.html\" title=\"class in p1\">A</a></dt>\n"
+            + "<dd>\n"
+            + "<div class=\"block\">First sentence i.e. the first sentence</div>\n"
+            + "</dd>\n"
+            + "</dl>\n",
+            "<div class=\"block\">The first... line</div>\n"
+        );
+
+        // make sure the second @summary's content is displayed correctly
+        checkOutput("p1/A.html", true,
+             "<li class=\"blockList\">\n"
+             + "<h4>m3</h4>\n"
+             + "<pre>public&nbsp;void&nbsp;m3&#8203;()</pre>\n"
+             + "<div class=\"block\">First sentence  some text maybe second sentence.</div>\n"
+             + "</li>\n"
+        );
+
+        checkOutput("p1/package-summary.html", true,
+                "<div class=\"block\">The first... line second from ...</div>");
+    }
+    @Test
+    void test2() {
+        javadoc("-d", "out2",
+                "-sourcepath", testSrc,
+                "p2");
+        checkExit(Exit.OK);
+
+        checkOutput(Output.OUT, true, "package.html:5: warning: invalid use of @summary");
+
+        checkOutput("index-all.html", true, "<div class=\"block\">foo bar</div>\n");
+
+        checkOutput("p2/package-summary.html", true, "<div class=\"block\">foo bar baz.</div>\n");
+    }
+
+    @Test
+    void test3() {
+        javadoc("-d", "out3",
+                "-sourcepath", testSrc,
+                "-overview", testSrc("p3/overview.html"),
+                "p3");
+        checkExit(Exit.OK);
+
+        checkOutput("overview-summary.html", true,
+                "<div class=\"block\">The first... line second from ...</div>");
+    }
+}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/langtools/test/jdk/javadoc/doclet/testSummaryTag/p1/A.java	Tue Aug 15 13:16:32 2017 -0700
@@ -0,0 +1,51 @@
+/*
+ * Copyright (c) 2017, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+package p1;
+
+public class A {
+    /**
+     * {@summary First sentence} Note no period after first sentence.
+     */
+    public void m() {}
+
+    /**
+     * <p> {@summary First sentence } Note the trailing whitespace.
+     */
+    public void m1() {}
+
+    /**
+     * {@summary Some html &lt;foo&gt; &nbsp; codes} Second sentence
+     */
+    public void m2() {}
+
+    /**
+     * {@summary First sentence } some text {@summary maybe second sentence}.
+     */
+    public void m3() {}
+
+    /**
+     * {@summary First sentence i.e. the first sentence} the second sentence.
+     */
+    public void m4() {}
+}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/langtools/test/jdk/javadoc/doclet/testSummaryTag/p1/B.java	Tue Aug 15 13:16:32 2017 -0700
@@ -0,0 +1,31 @@
+/*
+ * Copyright (c) 2017, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+package p1;
+
+public class B extends A {
+    /**
+     * {@inheritDoc} Third sentence.  Fourth sentence.
+     */
+    public void m() {}
+}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/langtools/test/jdk/javadoc/doclet/testSummaryTag/p1/package.html	Tue Aug 15 13:16:32 2017 -0700
@@ -0,0 +1,6 @@
+<HTML>
+ <BODY>
+   {@summary The first... line} second from ...
+ </BODY>
+</HTML>
+
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/langtools/test/jdk/javadoc/doclet/testSummaryTag/p2/A.java	Tue Aug 15 13:16:32 2017 -0700
@@ -0,0 +1,27 @@
+/*
+ * Copyright (c) 2017, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+package p2;
+
+/** The lonely class. */
+public class A {}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/langtools/test/jdk/javadoc/doclet/testSummaryTag/p2/package.html	Tue Aug 15 13:16:32 2017 -0700
@@ -0,0 +1,5 @@
+<HTML>
+ <BODY>
+    foo {@summary bar} baz.
+ </BODY>
+</HTML>
\ No newline at end of file
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/langtools/test/jdk/javadoc/doclet/testSummaryTag/p3/A.java	Tue Aug 15 13:16:32 2017 -0700
@@ -0,0 +1,27 @@
+/*
+ * Copyright (c) 2017, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+package p3;
+
+/** The lonely class. */
+public class A {}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/langtools/test/jdk/javadoc/doclet/testSummaryTag/p3/overview.html	Tue Aug 15 13:16:32 2017 -0700
@@ -0,0 +1,6 @@
+<HTML>
+ <BODY>
+   {@summary The first... line} second from ...
+ </BODY>
+</HTML>
+
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/langtools/test/tools/doclint/SummaryTest.java	Tue Aug 15 13:16:32 2017 -0700
@@ -0,0 +1,19 @@
+/*
+ * @test /nodynamiccopyright/
+ * @modules jdk.compiler/com.sun.tools.doclint
+ * @build DocLintTester
+ * @run main DocLintTester -ref SummaryTest.out SummaryTest.java
+ */
+
+/** No comment. */
+public class SummaryTest {
+    /**
+     {@summary legal} **/
+    public void m0() {}
+
+    /** <p> {@summary illegal} **/
+    public void m1() {}
+
+    /** {@summary legal} text {@summary illegal} **/
+    public void m2() {}
+}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/langtools/test/tools/doclint/SummaryTest.out	Tue Aug 15 13:16:32 2017 -0700
@@ -0,0 +1,7 @@
+SummaryTest.java:14: warning: invalid use of @summary
+    /** <p> {@summary illegal} **/
+            ^
+SummaryTest.java:17: warning: invalid use of @summary
+    /** {@summary legal} text {@summary illegal} **/
+                              ^
+2 warnings
--- a/langtools/test/tools/javac/completionDeps/DepsAndDocLint.java	Tue Aug 08 23:00:45 2017 +0000
+++ b/langtools/test/tools/javac/completionDeps/DepsAndDocLint.java	Tue Aug 15 13:16:32 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -21,7 +21,7 @@
  * questions.
  */
 
-/**
+/*
  * @test
  * @bug 8078389
  * @summary Make sure there is no interference between completionDeps and doclint
--- a/langtools/test/tools/javac/doctree/DocCommentTester.java	Tue Aug 08 23:00:45 2017 +0000
+++ b/langtools/test/tools/javac/doctree/DocCommentTester.java	Tue Aug 15 13:16:32 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -588,6 +588,17 @@
                 return null;
             }
 
+            @Override
+            public Void visitSummary(SummaryTree node, Void p) {
+                header(node);
+                indent(+1);
+                print("summary", node.getSummary());
+                indent(-1);
+                indent();
+                out.println("]");
+                return null;
+            }
+
             public Void visitText(TextTree node, Void p) {
                 header(node, compress(node.getBody()));
                 return null;
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/langtools/test/tools/javac/doctree/SummaryTest.java	Tue Aug 15 13:16:32 2017 -0700
@@ -0,0 +1,188 @@
+/*
+ * Copyright (c) 2017, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/*
+ * @test
+ * @bug 8173425
+ * @summary extend com.sun.source API to support parsing javadoc comments
+ * @modules jdk.compiler/com.sun.tools.javac.api
+ *          jdk.compiler/com.sun.tools.javac.file
+ *          jdk.compiler/com.sun.tools.javac.tree
+ *          jdk.compiler/com.sun.tools.javac.util
+ * @build DocCommentTester
+ * @run main DocCommentTester SummaryTest.java
+ */
+
+class SummaryTest {
+    /**
+     * {@summary} abc.
+     */
+    void empty() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 1
+    Summary[SUMMARY, pos:1
+      summary: empty
+    ]
+  body: 1
+    Text[TEXT, pos:11, _abc.]
+  block tags: empty
+]
+*/
+    /**
+     * {@summary abc} def.
+     */
+    void simple() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 1
+    Summary[SUMMARY, pos:1
+      summary: 1
+        Text[TEXT, pos:11, abc]
+    ]
+  body: 1
+    Text[TEXT, pos:15, _def.]
+  block tags: empty
+]
+*/
+
+    /**
+     *    {@summary abc} def
+     */
+    void leading_space() { }
+/*
+DocComment[DOC_COMMENT, pos:4
+  firstSentence: 1
+    Summary[SUMMARY, pos:4
+      summary: 1
+        Text[TEXT, pos:14, abc]
+    ]
+  body: 1
+    Text[TEXT, pos:18, _def]
+  block tags: empty
+]
+*/
+
+    /**
+     * <p> {@summary abc} def
+     */
+    void leading_html() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 3
+    StartElement[START_ELEMENT, pos:1
+      name:p
+      attributes: empty
+    ]
+    Text[TEXT, pos:4, _]
+    Summary[SUMMARY, pos:5
+      summary: 1
+        Text[TEXT, pos:15, abc]
+    ]
+  body: 1
+    Text[TEXT, pos:19, _def]
+  block tags: empty
+]
+*/
+
+    /**
+     * abc {@summary def} ghi
+     */
+    void leading_text() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 2
+    Text[TEXT, pos:1, abc_]
+    Summary[SUMMARY, pos:5
+      summary: 1
+        Text[TEXT, pos:15, def]
+    ]
+  body: 1
+    Text[TEXT, pos:19, _ghi]
+  block tags: empty
+]
+*/
+
+    /**
+     * abc. {@summary def} ghi
+     */
+    void leading_text_with_break() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 1
+    Text[TEXT, pos:1, abc.]
+  body: 2
+    Summary[SUMMARY, pos:6
+      summary: 1
+        Text[TEXT, pos:16, def]
+    ]
+    Text[TEXT, pos:20, _ghi]
+  block tags: empty
+]
+*/
+
+    /**
+     * {@summary def} <p> ghi
+     */
+    void trailing_html() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 1
+    Summary[SUMMARY, pos:1
+      summary: 1
+        Text[TEXT, pos:11, def]
+    ]
+  body: 3
+    Text[TEXT, pos:15, _]
+    StartElement[START_ELEMENT, pos:16
+      name:p
+      attributes: empty
+    ]
+    Text[TEXT, pos:19, _ghi]
+  block tags: empty
+]
+*/
+
+    /**
+     * {@summary abc &lt;def&gt; ghi} jkl
+     */
+    void with_html() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 1
+    Summary[SUMMARY, pos:1
+      summary: 5
+        Text[TEXT, pos:11, abc_]
+        Entity[ENTITY, pos:15, lt]
+        Text[TEXT, pos:19, def]
+        Entity[ENTITY, pos:22, gt]
+        Text[TEXT, pos:26, _ghi]
+    ]
+  body: 1
+    Text[TEXT, pos:31, _jkl]
+  block tags: empty
+]
+*/
+}
--- a/langtools/test/tools/javac/lib/DPrinter.java	Tue Aug 08 23:00:45 2017 +0000
+++ b/langtools/test/tools/javac/lib/DPrinter.java	Tue Aug 15 13:16:32 2017 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2013, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2013, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -1136,6 +1136,12 @@
             return visitBlockTag(node, null);
         }
 
+        public Void visitSummary(SummaryTree node, Void p) {
+            printString("name", node.getTagName());
+            printList("summary", node.getSummary());
+            return visitInlineTag(node, null);
+        }
+
         public Void visitText(TextTree node, Void p) {
             printLimitedEscapedString("body", node.getBody());
             return visitTree(node, null);