infernap12/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2026-03-06 22:20:47 +00:00
Code Issues Packages Projects Releases Wiki Activity

8173425: Javadoc needs a new tag to specify the summary

Browse Source 
Reviewed-by: jjg
This commit is contained in:
Kumar Srinivasan 2017-08-15 13:16:32 -07:00
parent d15ccc0eb9
commit 1dd6fa2fb6
29 changed files with 767 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
langtools/src/jdk.compiler/share/classes/com/sun/source/doctree/DocTree.java
View File

@ -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
@ -204,6 +204,12 @@ public interface DocTree {
*/
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.

13
langtools/src/jdk.compiler/share/classes/com/sun/source/doctree/DocTreeVisitor.java
View File

@ -256,6 +256,19 @@ public interface DocTreeVisitor<R,P> {
*/
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

44
langtools/src/jdk.compiler/share/classes/com/sun/source/doctree/SummaryTree.java Normal file
View File

@ -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();
}

16
langtools/src/jdk.compiler/share/classes/com/sun/source/util/DocTreeFactory.java
View File

@ -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.SerialFieldTree;
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;
@ -287,6 +288,19 @@ public interface DocTreeFactory {
*/
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

16
langtools/src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java
View File

@ -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
@ -437,6 +437,20 @@ public class DocTreeScanner<R,P> implements DocTreeVisitor<R,P> {
return scan(node.getAttributes(), p);
}
/**
* {@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}.
*

15
langtools/src/jdk.compiler/share/classes/com/sun/source/util/SimpleDocTreeVisitor.java
View File

@ -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
@ -395,6 +395,19 @@ public class SimpleDocTreeVisitor<R,P> implements DocTreeVisitor<R, P> {
return defaultAction(node, p);
}
/**
* {@inheritDoc} This implementation calls {@code defaultAction}.
*
* @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}.
*

18
langtools/src/jdk.compiler/share/classes/com/sun/tools/doclint/Checker.java
View File

@ -70,6 +70,7 @@ import com.sun.source.doctree.SerialDataTree;
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 @@ public class Checker extends DocTreePathScanner<Void, Void> {
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 @@ public class Checker extends DocTreePathScanner<Void, Void> {
foundThrows.clear();
foundInheritDoc = false;
foundReturn = false;
hasNonWhitespaceText = false;
scan(new DocTreePath(p, tree), null);
@ -245,7 +248,8 @@ public class Checker extends DocTreePathScanner<Void, Void> {
@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);
}
@ -905,6 +909,17 @@ public class Checker extends DocTreePathScanner<Void, Void> {
return super.visitSince(tree, ignore);
}
@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();
@ -1091,6 +1106,7 @@ public class Checker extends DocTreePathScanner<Void, Void> {
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;
}

1
langtools/src/jdk.compiler/share/classes/com/sun/tools/doclint/resources/doclint.properties
View File

@ -45,6 +45,7 @@ dc.invalid.anchor = invalid name for anchor: "{0}"
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}"

10
langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java
View File

@ -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 @@ public class DocCommentParser {
}
},
// @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 {

25
langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DCTree.java
View File

@ -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 abstract class DCTree implements DocTree {
}
}
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;

18
langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DocPretty.java
View File

@ -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
@ -502,6 +502,22 @@ public class DocPretty implements DocTreeVisitor<Void,Void> {
return null;
}
@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 {

13
langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DocTreeMaker.java
View File

@ -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.DCSerialData;
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;
@ -411,6 +412,13 @@ public class DocTreeMaker implements DocTreeFactory {
return tree;
}
@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);
@ -497,6 +505,9 @@ public class DocTreeMaker implements DocTreeFactory {
continue;
}
switch (dt.getKind()) {
case SUMMARY:
foundFirstSentence = true;
break;
case TEXT:
DCText tt = (DCText) dt;
String s = tt.getBody();

10
langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java
View File

@ -60,6 +60,7 @@ import com.sun.source.doctree.LinkTree;
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 @@ public class HtmlDocletWriter extends HtmlDocWriter {
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);
}

57
langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SummaryTaglet.java Normal file
View File

@ -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());
}
}

1
langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletManager.java
View File

@ -726,6 +726,7 @@ public class TagletManager {
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.

123
langtools/test/jdk/javadoc/doclet/testSummaryTag/TestSummaryTag.java Normal file
View File

@ -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>");
}
}

51
langtools/test/jdk/javadoc/doclet/testSummaryTag/p1/A.java Normal file
View File

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

31
langtools/test/jdk/javadoc/doclet/testSummaryTag/p1/B.java Normal file
View File

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

6
langtools/test/jdk/javadoc/doclet/testSummaryTag/p1/package.html Normal file
View File

@ -0,0 +1,6 @@
<HTML>
<BODY>
{@summary The first... line} second from ...
</BODY>
</HTML>

27
langtools/test/jdk/javadoc/doclet/testSummaryTag/p2/A.java Normal file
View File

@ -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 {}

5
langtools/test/jdk/javadoc/doclet/testSummaryTag/p2/package.html Normal file
View File

@ -0,0 +1,5 @@
<HTML>
<BODY>
foo {@summary bar} baz.
</BODY>
</HTML>

27
langtools/test/jdk/javadoc/doclet/testSummaryTag/p3/A.java Normal file
View File

@ -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 {}

6
langtools/test/jdk/javadoc/doclet/testSummaryTag/p3/overview.html Normal file
View File

@ -0,0 +1,6 @@
<HTML>
<BODY>
{@summary The first... line} second from ...
</BODY>
</HTML>

19
langtools/test/tools/doclint/SummaryTest.java Normal file
View File

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

7
langtools/test/tools/doclint/SummaryTest.out Normal file
View File

@ -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

4
langtools/test/tools/javac/completionDeps/DepsAndDocLint.java
View File

@ -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

13
langtools/test/tools/javac/doctree/DocCommentTester.java
View File

@ -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 @@ public class DocCommentTester {
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;

188
langtools/test/tools/javac/doctree/SummaryTest.java Normal file
View File

@ -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
]
*/
}

8
langtools/test/tools/javac/lib/DPrinter.java
View File

@ -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 @@ public class DPrinter {
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);