--- 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>
+ * {@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 <foo> 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 void m3​()</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 <foo> 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 <def> 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);