diff --git a/langtools/src/share/classes/com/sun/source/util/DocSourcePositions.java b/langtools/src/share/classes/com/sun/source/util/DocSourcePositions.java new file mode 100644 index 00000000000..d249da1c278 --- /dev/null +++ b/langtools/src/share/classes/com/sun/source/util/DocSourcePositions.java @@ -0,0 +1,98 @@ +/* + * Copyright (c) 2013, 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.util; + +import com.sun.source.doctree.DocCommentTree; +import com.sun.source.doctree.DocTree; +import com.sun.source.tree.CompilationUnitTree; + +/** + * Provides methods to obtain the position of a DocTree within a javadoc comment. + * A position is defined as a simple character offset from the start of a + * CompilationUnit where the first character is at offset 0. + * + * @since 1.8 + */ +@jdk.Supported +public interface DocSourcePositions extends SourcePositions { + + /** + * Gets the starting position of the tree within the comment within the file. If tree is not found within + * file, or if the starting position is not available, + * return {@link javax.tools.Diagnostic#NOPOS}. + * The given tree should be under the given comment tree, and the given documentation + * comment tree should be returned from a {@link DocTrees#getDocCommentTree(com.sun.source.util.TreePath) } + * for a tree under the given file. + * The returned position must be at the start of the yield of this tree, that + * is for any sub-tree of this tree, the following must hold: + * + *

+ * {@code tree.getStartPosition() <= subtree.getStartPosition()} or
+ * {@code tree.getStartPosition() == NOPOS} or
+ * {@code subtree.getStartPosition() == NOPOS} + *

+ * + * @param file CompilationUnit in which to find tree. + * @param comment the comment tree that encloses the tree for which the + * position is being sought + * @param tree tree for which a position is sought. + * @return the start position of tree. + */ + long getStartPosition(CompilationUnitTree file, DocCommentTree comment, DocTree tree); + + /** + * Gets the ending position of the tree within the comment within the file. If tree is not found within + * file, or if the ending position is not available, + * return {@link javax.tools.Diagnostic#NOPOS}. + * The given tree should be under the given comment tree, and the given documentation + * comment tree should be returned from a {@link DocTrees#getDocCommentTree(com.sun.source.util.TreePath) } + * for a tree under the given file. + * The returned position must be at the end of the yield of this tree, + * that is for any sub-tree of this tree, the following must hold: + * + *

+ * {@code tree.getEndPosition() >= subtree.getEndPosition()} or
+ * {@code tree.getEndPosition() == NOPOS} or
+ * {@code subtree.getEndPosition() == NOPOS} + *

+ * + * In addition, the following must hold: + * + *

+ * {@code tree.getStartPosition() <= tree.getEndPosition()} or
+ * {@code tree.getStartPosition() == NOPOS} or
+ * {@code tree.getEndPosition() == NOPOS} + *

+ * + * @param file CompilationUnit in which to find tree. + * @param comment the comment tree that encloses the tree for which the + * position is being sought + * @param tree tree for which a position is sought. + * @return the start position of tree. + */ + long getEndPosition(CompilationUnitTree file, DocCommentTree comment, DocTree tree); + +} diff --git a/langtools/src/share/classes/com/sun/source/util/DocTrees.java b/langtools/src/share/classes/com/sun/source/util/DocTrees.java index 63f6c899c20..94f68bbd4a7 100644 --- a/langtools/src/share/classes/com/sun/source/util/DocTrees.java +++ b/langtools/src/share/classes/com/sun/source/util/DocTrees.java @@ -72,6 +72,8 @@ public abstract class DocTrees extends Trees { */ public abstract Element getElement(TreePath path, ReferenceTree reference); + public abstract DocSourcePositions getSourcePositions(); + /** * Prints a message of the specified kind at the location of the * tree within the provided compilation unit diff --git a/langtools/src/share/classes/com/sun/source/util/SourcePositions.java b/langtools/src/share/classes/com/sun/source/util/SourcePositions.java index d55c73135ab..4494d320434 100644 --- a/langtools/src/share/classes/com/sun/source/util/SourcePositions.java +++ b/langtools/src/share/classes/com/sun/source/util/SourcePositions.java @@ -59,7 +59,7 @@ public interface SourcePositions { /** * Gets the ending position of tree within file. If tree is not found within - * file, or if the starting position is not available, + * file, or if the ending position is not available, * return {@link javax.tools.Diagnostic#NOPOS}. * The returned position must be at the end of the yield of this tree, * that is for any sub-tree of this tree, the following must hold: diff --git a/langtools/src/share/classes/com/sun/tools/javac/api/JavacTrees.java b/langtools/src/share/classes/com/sun/tools/javac/api/JavacTrees.java index 490490178fb..545b883f7f0 100644 --- a/langtools/src/share/classes/com/sun/tools/javac/api/JavacTrees.java +++ b/langtools/src/share/classes/com/sun/tools/javac/api/JavacTrees.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2005, 2012, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2005, 2013, 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 @@ -43,14 +43,16 @@ import javax.tools.JavaCompiler; import javax.tools.JavaFileObject; import com.sun.source.doctree.DocCommentTree; +import com.sun.source.doctree.DocTree; import com.sun.source.doctree.ReferenceTree; import com.sun.source.tree.CatchTree; import com.sun.source.tree.CompilationUnitTree; import com.sun.source.tree.Scope; import com.sun.source.tree.Tree; +import com.sun.source.util.DocSourcePositions; +import com.sun.source.util.DocTreeScanner; import com.sun.source.util.DocTrees; import com.sun.source.util.JavacTask; -import com.sun.source.util.SourcePositions; import com.sun.source.util.TreePath; import com.sun.tools.javac.code.Flags; import com.sun.tools.javac.code.Kinds; @@ -76,8 +78,14 @@ import com.sun.tools.javac.comp.Resolve; import com.sun.tools.javac.model.JavacElements; import com.sun.tools.javac.processing.JavacProcessingEnvironment; import com.sun.tools.javac.tree.DCTree; +import com.sun.tools.javac.tree.DCTree.DCBlockTag; import com.sun.tools.javac.tree.DCTree.DCDocComment; +import com.sun.tools.javac.tree.DCTree.DCEndPosTree; +import com.sun.tools.javac.tree.DCTree.DCErroneous; +import com.sun.tools.javac.tree.DCTree.DCIdentifier; +import com.sun.tools.javac.tree.DCTree.DCParam; import com.sun.tools.javac.tree.DCTree.DCReference; +import com.sun.tools.javac.tree.DCTree.DCText; import com.sun.tools.javac.tree.EndPosTable; import com.sun.tools.javac.tree.JCTree; import com.sun.tools.javac.tree.JCTree.*; @@ -94,6 +102,7 @@ import com.sun.tools.javac.util.Log; import com.sun.tools.javac.util.Name; import com.sun.tools.javac.util.Names; import com.sun.tools.javac.util.Pair; +import com.sun.tools.javac.util.Position; import static com.sun.tools.javac.code.TypeTag.*; /** @@ -166,8 +175,8 @@ public class JavacTrees extends DocTrees { javacTaskImpl = (JavacTaskImpl) t; } - public SourcePositions getSourcePositions() { - return new SourcePositions() { + public DocSourcePositions getSourcePositions() { + return new DocSourcePositions() { public long getStartPosition(CompilationUnitTree file, Tree tree) { return TreeInfo.getStartPos((JCTree) tree); } @@ -176,9 +185,80 @@ public class JavacTrees extends DocTrees { EndPosTable endPosTable = ((JCCompilationUnit) file).endPositions; return TreeInfo.getEndPos((JCTree) tree, endPosTable); } + + public long getStartPosition(CompilationUnitTree file, DocCommentTree comment, DocTree tree) { + return ((DCTree) tree).getSourcePosition((DCDocComment) comment); + } + @SuppressWarnings("fallthrough") + public long getEndPosition(CompilationUnitTree file, DocCommentTree comment, DocTree tree) { + DCDocComment dcComment = (DCDocComment) comment; + if (tree instanceof DCEndPosTree) { + int endPos = ((DCEndPosTree) tree).getEndPos(dcComment); + + if (endPos != Position.NOPOS) { + return endPos; + } + } + int correction = 0; + switch (tree.getKind()) { + case TEXT: + DCText text = (DCText) tree; + + return dcComment.comment.getSourcePos(text.pos + text.text.length()); + case ERRONEOUS: + DCErroneous err = (DCErroneous) tree; + + return dcComment.comment.getSourcePos(err.pos + err.body.length()); + case IDENTIFIER: + DCIdentifier ident = (DCIdentifier) tree; + + return dcComment.comment.getSourcePos(ident.pos + (ident.name != names.error ? ident.name.length() : 0)); + case PARAM: + DCParam param = (DCParam) tree; + + if (param.isTypeParameter && param.getDescription().isEmpty()) { + correction = 1; + } + case AUTHOR: case DEPRECATED: case RETURN: case SEE: + case SERIAL: case SERIAL_DATA: case SERIAL_FIELD: case SINCE: + case THROWS: case UNKNOWN_BLOCK_TAG: case VERSION: { + DocTree last = getLastChild(tree); + + if (last != null) { + return getEndPosition(file, comment, last) + correction; + } + + DCBlockTag block = (DCBlockTag) tree; + + return dcComment.comment.getSourcePos(block.pos + block.getTagName().length() + 1); + } + default: + DocTree last = getLastChild(tree); + + if (last != null) { + return getEndPosition(file, comment, last); + } + break; + } + + return Position.NOPOS; + } }; } + private DocTree getLastChild(DocTree tree) { + final DocTree[] last = new DocTree[] {null}; + + tree.accept(new DocTreeScanner() { + @Override public Void scan(DocTree node, Void p) { + if (node != null) last[0] = node; + return null; + } + }, null); + + return last[0]; + } + public JCClassDecl getTree(TypeElement element) { return (JCClassDecl) getTree((Element) element); } diff --git a/langtools/src/share/classes/com/sun/tools/javac/parser/DocCommentParser.java b/langtools/src/share/classes/com/sun/tools/javac/parser/DocCommentParser.java index bbc4d81d5c7..535dbd2692e 100644 --- a/langtools/src/share/classes/com/sun/tools/javac/parser/DocCommentParser.java +++ b/langtools/src/share/classes/com/sun/tools/javac/parser/DocCommentParser.java @@ -41,6 +41,7 @@ import com.sun.tools.javac.tree.DCTree; import com.sun.tools.javac.tree.DCTree.DCAttribute; import com.sun.tools.javac.tree.DCTree.DCDocComment; import com.sun.tools.javac.tree.DCTree.DCEndElement; +import com.sun.tools.javac.tree.DCTree.DCEndPosTree; import com.sun.tools.javac.tree.DCTree.DCErroneous; import com.sun.tools.javac.tree.DCTree.DCIdentifier; import com.sun.tools.javac.tree.DCTree.DCReference; @@ -336,12 +337,12 @@ public class DocCommentParser { DCTree text = inlineText(); if (text != null) { nextChar(); - return m.at(p).UnknownInlineTag(name, List.of(text)); + return m.at(p).UnknownInlineTag(name, List.of(text)).setEndPos(bp); } } else if (tp.getKind() == TagParser.Kind.INLINE) { - DCTree tree = tp.parse(p); + DCEndPosTree tree = (DCEndPosTree) tp.parse(p); if (tree != null) { - return tree; + return tree.setEndPos(bp); } } else { inlineText(); // skip content @@ -509,7 +510,7 @@ public class DocCommentParser { fac.log.popDiagnosticHandler(deferredDiagnosticHandler); } - return m.at(pos).Reference(sig, qualExpr, member, paramTypes); + return m.at(pos).Reference(sig, qualExpr, member, paramTypes).setEndPos(bp); } JCTree parseType(String s) throws ParseException { @@ -741,7 +742,7 @@ public class DocCommentParser { } if (ch == '>') { nextChar(); - return m.at(p).StartElement(name, attrs, selfClosing); + return m.at(p).StartElement(name, attrs, selfClosing).setEndPos(bp); } } } else if (ch == '/') { diff --git a/langtools/src/share/classes/com/sun/tools/javac/tree/DCTree.java b/langtools/src/share/classes/com/sun/tools/javac/tree/DCTree.java index c2ca23caf4b..2f4e6dd3a48 100644 --- a/langtools/src/share/classes/com/sun/tools/javac/tree/DCTree.java +++ b/langtools/src/share/classes/com/sun/tools/javac/tree/DCTree.java @@ -36,6 +36,7 @@ import com.sun.tools.javac.util.JCDiagnostic; import com.sun.tools.javac.util.JCDiagnostic.SimpleDiagnosticPosition; import com.sun.tools.javac.util.List; import com.sun.tools.javac.util.Name; +import com.sun.tools.javac.util.Position; import java.io.IOException; import java.io.StringWriter; import javax.tools.JavaFileObject; @@ -82,8 +83,24 @@ public abstract class DCTree implements DocTree { return s.toString(); } + public static abstract class DCEndPosTree> extends DCTree { + + private int endPos = Position.NOPOS; + + public int getEndPos(DCDocComment dc) { + return dc.comment.getSourcePos(endPos); + } + + @SuppressWarnings("unchecked") + public T setEndPos(int endPos) { + this.endPos = endPos; + return (T) this; + } + + } + public static class DCDocComment extends DCTree implements DocCommentTree { - final Comment comment; // required for the implicit source pos table + public final Comment comment; // required for the implicit source pos table public final List firstSentence; public final List body; @@ -125,7 +142,7 @@ public abstract class DCTree implements DocTree { } } - public static abstract class DCInlineTag extends DCTree implements InlineTagTree { + public static abstract class DCInlineTag extends DCEndPosTree implements InlineTagTree { public String getTagName() { return getKind().tagName; } @@ -345,6 +362,7 @@ public abstract class DCTree implements DocTree { public int getEndPosition(EndPosTable endPosTable) { return pos + body.length(); } + } public static class DCIdentifier extends DCTree implements IdentifierTree { @@ -478,7 +496,7 @@ public abstract class DCTree implements DocTree { } } - public static class DCReference extends DCTree implements ReferenceTree { + public static class DCReference extends DCEndPosTree implements ReferenceTree { public final String signature; // The following are not directly exposed through ReferenceTree @@ -663,7 +681,7 @@ public abstract class DCTree implements DocTree { } } - public static class DCStartElement extends DCTree implements StartElementTree { + public static class DCStartElement extends DCEndPosTree implements StartElementTree { public final Name name; public final List attrs; public final boolean selfClosing; diff --git a/langtools/test/tools/javac/doctree/positions/TestPosition.java b/langtools/test/tools/javac/doctree/positions/TestPosition.java new file mode 100644 index 00000000000..8d03c8d165f --- /dev/null +++ b/langtools/test/tools/javac/doctree/positions/TestPosition.java @@ -0,0 +1,105 @@ +/* + * Copyright (c) 2010, 2013, 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. + */ + +/* + * @test + * @bug 8008174 + * @summary proper source positions for doc comments + * @build TestPosition + * @compile/ref=TestPosition.out -processor TestPosition -proc:only TestPositionSource.java + */ + +import com.sun.source.doctree.DocCommentTree; +import com.sun.source.doctree.DocTree; +import com.sun.source.tree.MethodTree; +import com.sun.source.util.DocSourcePositions; +import com.sun.source.util.DocTreeScanner; +import com.sun.source.util.DocTrees; +import com.sun.source.util.TreePath; +import com.sun.source.util.TreePathScanner; +import java.io.IOException; +import java.util.Set; +import javax.annotation.processing.*; +import javax.lang.model.*; +import javax.lang.model.element.*; + +@SupportedAnnotationTypes("*") +public class TestPosition extends AbstractProcessor { + + @Override + public boolean process(Set annotations, RoundEnvironment roundEnv) { + TypeElement source = processingEnv.getElementUtils().getTypeElement("TestPositionSource"); + + if (source == null) throw new IllegalStateException(); + + if (!roundEnv.getRootElements().contains(source)) return false; + + final DocTrees trees = DocTrees.instance(processingEnv); + final TreePath testElement = trees.getPath(source); + + if (testElement == null) throw new IllegalStateException(); + + String code; + + try { + code = testElement.getCompilationUnit().getSourceFile().getCharContent(false).toString(); + } catch ( IOException ex) { + throw new IllegalStateException(ex); + } + + new TreePathScanner() { + @Override public Void visitMethod(MethodTree node, Void p) { + final DocCommentTree docCommentTree = trees.getDocCommentTree(getCurrentPath()); + + if (docCommentTree != null) { + System.out.println(node.getName() + ":"); + new DocTreeScanner() { + @Override public Void scan(DocTree node, Void p) { + if (node != null) { + DocSourcePositions sp = (DocSourcePositions) trees.getSourcePositions(); //XXX: the cast??? + int start = (int) sp.getStartPosition(testElement.getCompilationUnit(), docCommentTree, node); + int end = (int) sp.getEndPosition(testElement.getCompilationUnit(), docCommentTree, node); + String snippet = code.substring(start, end).replace(" \n", "!trailing-whitespace!\n"); + + if (snippet.endsWith(" ")) { + snippet = snippet.substring(0, snippet.length() - 1) + "!trailing-whitespace!"; + } + System.out.println(node.getKind().name() + ":" + snippet); + } + return super.scan(node, p); + } + }.scan(docCommentTree, null); + } + + return super.visitMethod(node, p); + } + }.scan(testElement, null); + + return false; + } + + @Override + public SourceVersion getSupportedSourceVersion() { + return SourceVersion.latest(); + } +} diff --git a/langtools/test/tools/javac/doctree/positions/TestPosition.out b/langtools/test/tools/javac/doctree/positions/TestPosition.out new file mode 100644 index 00000000000..36a386866a8 --- /dev/null +++ b/langtools/test/tools/javac/doctree/positions/TestPosition.out @@ -0,0 +1,99 @@ +valid: +DOC_COMMENT:First sentence. + * + *

Description with {@link java.io.InputStream link} + * + * @param first description + * @param second description + * @return whatever + * @throws IllegalStateException why? + * @since 1.15 + * @see java.util.List +TEXT:First sentence. +START_ELEMENT:

+TEXT:Description with!trailing-whitespace! +LINK:{@link java.io.InputStream link} +REFERENCE:java.io.InputStream +TEXT:link +PARAM:@param first description +IDENTIFIER:first +TEXT:description +PARAM:@param second description +IDENTIFIER:second +TEXT:description +RETURN:@return whatever +TEXT:whatever +THROWS:@throws IllegalStateException why? +REFERENCE:IllegalStateException +TEXT:why? +SINCE:@since 1.15 +TEXT:1.15 +SEE:@see java.util.List +REFERENCE:java.util.List +erroneous: +DOC_COMMENT:First sentence. + * + *

Description with {@link}, {@link java.util.List}, {@link + * + * @param + * @param second + * @return + * @throws + * @throws IllegalStateException + * @since + * @see +TEXT:First sentence. +START_ELEMENT:

+TEXT:Description with!trailing-whitespace! +LINK:{@link} +TEXT:,!trailing-whitespace! +LINK:{@link java.util.List} +REFERENCE:java.util.List +TEXT:,!trailing-whitespace! +ERRONEOUS:{@link +ERRONEOUS:@param +PARAM:@param second +IDENTIFIER:second +RETURN:@return +ERRONEOUS:@throws +THROWS:@throws IllegalStateException +REFERENCE:IllegalStateException +SINCE:@since +ERRONEOUS:@see +withWhiteSpaces: +DOC_COMMENT:First sentence. + * + *

Description with {@link }, {@link java.util.List#add( int )}, + * {@link java.util.List#add( int ) some text with whitespaces}, {@link + * + * @param first + * @param second some text with trailing whitespace + * @return some return + * @throws java.lang.IllegalStateException + * @throws java.lang.IllegalStateException some text +TEXT:First sentence. +START_ELEMENT:

+TEXT:Description with!trailing-whitespace! +LINK:{@link } +TEXT:,!trailing-whitespace! +LINK:{@link java.util.List#add( int )} +REFERENCE:java.util.List#add( int ) +TEXT:, + *!trailing-whitespace! +LINK:{@link java.util.List#add( int ) some text with whitespaces} +REFERENCE:java.util.List#add( int ) +TEXT:some text with whitespaces +TEXT:,!trailing-whitespace! +ERRONEOUS:{@link +PARAM:@param first +IDENTIFIER:first +PARAM:@param second some text with trailing whitespace +IDENTIFIER:second +TEXT:some text with trailing whitespace +RETURN:@return some return +TEXT:some return +THROWS:@throws java.lang.IllegalStateException +REFERENCE:java.lang.IllegalStateException +THROWS:@throws java.lang.IllegalStateException some text +REFERENCE:java.lang.IllegalStateException +TEXT:some text \ No newline at end of file diff --git a/langtools/test/tools/javac/doctree/positions/TestPositionSource.java b/langtools/test/tools/javac/doctree/positions/TestPositionSource.java new file mode 100644 index 00000000000..801af3d687c --- /dev/null +++ b/langtools/test/tools/javac/doctree/positions/TestPositionSource.java @@ -0,0 +1,71 @@ +/* + * Copyright (c) 2010, 2013, 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. + */ +public class TestPositionSource { + + /**First sentence. + * + *

Description with {@link java.io.InputStream link} + * + * @param first description + * @param second description + * @return whatever + * @throws IllegalStateException why? + * @since 1.15 + * @see java.util.List + */ + public boolean valid(int first, int second) throws IllegalStateException { + return true; + } + + /**First sentence. + * + *

Description with {@link}, {@link java.util.List}, {@link + * + * @param + * @param second + * @return + * @throws + * @throws IllegalStateException + * @since + * @see + */ + public boolean erroneous(int first, int second) throws IllegalStateException { + return true; + } + + /**First sentence. + * + *

Description with {@link }, {@link java.util.List#add( int )}, + * {@link java.util.List#add( int ) some text with whitespaces}, {@link + * + * @param first + * @param second some text with trailing whitespace + * @return some return + * @throws java.lang.IllegalStateException + * @throws java.lang.IllegalStateException some text + */ + public boolean withWhiteSpaces(int first, int second) throws IllegalStateException { + return true; + } + +}