7021614: extend com.sun.source API to support parsing javadoc comments

Reviewed-by: ksrini, strarup

langtools/make/build.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
- Copyright (c) 2007, 2011, Oracle and/or its affiliates. All rights reserved.
+ Copyright (c) 2007, 2012, 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
@@ -277,7 +277,7 @@
         <!-- transform the output to a simple html -->
         <xslt  in="${dist.checkstyle.dir}/checkstyle_report.xml"
                out="${dist.checkstyle.dir}/checkstyle_report.html"
-               style="${checkstyle.home}/contrib/checkstyle-simple.xsl"/>            
+               style="${checkstyle.home}/contrib/checkstyle-simple.xsl"/>
         <!-- transform the output to a very simple emacs friendly text file -->
         <xslt  in="${dist.checkstyle.dir}/checkstyle_report.xml"
                out="${dist.checkstyle.dir}/checkstyle_report.tmp"
@@ -297,9 +297,9 @@
     <target name="checkstyle-ide" depends="checkstyle">
         <concat>
             <fileset file="${dist.checkstyle.dir}/checkstyle_report.emacs.txt"/>
-        </concat>  
+        </concat>
     </target>
-    
+
     <target name="findbugs" depends="-def-findbugs,build-all-tools">
         <property name="findbugs.reportLevel" value="medium"/>
         <mkdir dir="${dist.findbugs.dir}"/>
@@ -368,7 +368,7 @@
             executable="${dist.bin.dir}/javac"
             srcdir="test/tools/javac/diags"
             destdir="${build.dir}/diag-examples/classes"
-            includes="ArgTypeCompilerFactory.java,Example.java,FileManager.java,HTMLWriter.java,RunExamples.java"
+            includes="ArgTypeCompilerFactory.java,Example.java,FileManager.java,HTMLWriter.java,RunExamples.java,DocCommentProcessor.java"
             sourcepath=""
             classpath="${dist.lib.dir}/javac.jar"
             includeAntRuntime="no"
@@ -381,6 +381,7 @@
             dir="test/tools/javac/diags"
             classpath="${build.dir}/diag-examples/classes;${dist.lib.dir}/javac.jar"
             classname="RunExamples">
+            <jvmarg value="-Dtest.classes=${build.dir}/diag-examples/classes"/>
             <arg value="-examples"/>
             <arg value="examples"/>
             <arg value="-o"/>
@@ -695,7 +696,7 @@
     <target name="-check-checkstyle.home" depends="-def-check">
         <check name="checkstyle" property="checkstyle.home" marker="${checkstyle.name.version}.jar"/>
     </target>
-    
+
     <target name="-check-jtreg.home" depends="-def-check">
         <check name="jtreg" property="jtreg.home" marker="lib/jtreg.jar"/>
     </target>
@@ -1005,7 +1006,7 @@
         </taskdef>
         <property name="checkstyle.defined" value="true"/>
     </target>
-    
+
     <target name="-def-findbugs" unless="findbugs.defined"
         depends="-check-findbugs.home,-check-target.java.home">
         <taskdef name="findbugs" classname="edu.umd.cs.findbugs.anttask.FindBugsTask">

langtools/src/share/classes/com/sun/source/doctree/AttributeTree.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright (c) 2011, 2012, 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;
+import javax.lang.model.element.Name;
+
+/**
+ * A tree node for an attribute in an HTML element.
+ *
+ * @since 1.8
+ */
+public interface AttributeTree extends DocTree {
+    enum ValueKind { EMPTY, UNQUOTED, SINGLE, DOUBLE };
+
+    Name getName();
+    ValueKind getValueKind();
+    List<? extends DocTree> getValue();
+}

langtools/src/share/classes/com/sun/source/doctree/AuthorTree.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright (c) 2011, 2012, 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 @author block tag.
+ *
+ * <p>
+ * &#064;author name-text.
+ *
+ * @since 1.8
+ */
+public interface AuthorTree extends BlockTagTree {
+    List<? extends DocTree> getName();
+}

langtools/src/share/classes/com/sun/source/doctree/BlockTagTree.java

@@ -0,0 +1,36 @@
+/*
+ * Copyright (c) 2011, 2012, 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;
+
+/**
+ * A tree node used as the base class for the different types of
+ * block tags.
+ *
+ * @since 1.8
+ */
+public interface BlockTagTree extends DocTree {
+    String getTagName();
+}

langtools/src/share/classes/com/sun/source/doctree/CommentTree.java

@@ -0,0 +1,39 @@
+/*
+ * Copyright (c) 2011, 2012, 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;
+
+/**
+ * An embedded HTML comment.
+ *
+ * <p>
+ * {@literal <!-- text --> }
+ *
+ * @since 1.8
+ */
+public interface CommentTree extends DocTree {
+    String getBody();
+}
+

langtools/src/share/classes/com/sun/source/doctree/DeprecatedTree.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright (c) 2011, 2012, 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 @deprecated block tag.
+ *
+ * <p>
+ * &#064;deprecated deprecated text.
+ *
+ * @since 1.8
+ */
+public interface DeprecatedTree extends BlockTagTree {
+    List<? extends DocTree> getBody();
+}

langtools/src/share/classes/com/sun/source/doctree/DocCommentTree.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright (c) 2011, 2012, 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;
+
+/**
+ * The top level representation of a documentation comment.
+ *
+ * <p>
+ * first-sentence body block-tags
+ *
+ * @since 1.8
+ */
+public interface DocCommentTree extends DocTree {
+    List<? extends DocTree> getFirstSentence();
+    List<? extends DocTree> getBody();
+    List<? extends DocTree> getBlockTags();
+}

langtools/src/share/classes/com/sun/source/doctree/DocRootTree.java

@@ -0,0 +1,36 @@
+/*
+ * Copyright (c) 2011, 2012, 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;
+
+/**
+ * A tree node for an @docroot inline tag.
+ *
+ * <p>
+ * {&#064;docroot}
+ *
+ * @since 1.8
+ */
+public interface DocRootTree extends InlineTagTree { }

langtools/src/share/classes/com/sun/source/doctree/DocTree.java

@@ -0,0 +1,254 @@
+/*
+ * Copyright (c) 2011, 2012, 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;
+
+/**
+ * Common interface for all nodes in a documentation syntax tree.
+ *
+ * @since 1.8
+ */
+public interface DocTree {
+    enum Kind {
+        /**
+         * Used for instances of {@link AttributeTree}
+         * representing an HTML attribute.
+         */
+        ATTRIBUTE,
+
+        /**
+         * Used for instances of {@link AuthorTree}
+         * representing an @author tag.
+         */
+        AUTHOR("author"),
+
+        /**
+         * Used for instances of {@link LiteralTree}
+         * representing an @code tag.
+         */
+        CODE("code"),
+
+        /**
+         * Used for instances of {@link CommentTree}
+         * representing an HTML comment.
+         */
+        COMMENT,
+
+        /**
+         * Used for instances of {@link DeprecatedTree}
+         * representing an @deprecated tag.
+         */
+        DEPRECATED("deprecated"),
+
+        /**
+         * Used for instances of {@link DocCommentTree}
+         * representing a complete doc comment.
+         */
+        DOC_COMMENT,
+
+        /**
+         * Used for instances of {@link DocRootTree}
+         * representing an @docRoot tag.
+         */
+        DOC_ROOT("docRoot"),
+
+        /**
+         * Used for instances of {@link EndElementTree}
+         * representing the end of an HTML element.
+         */
+        END_ELEMENT,
+
+        /**
+         * Used for instances of {@link EntityTree}
+         * representing an HTML entity.
+         */
+        ENTITY,
+
+        /**
+         * Used for instances of {@link ErroneousTree}
+         * representing some invalid text.
+         */
+        ERRONEOUS,
+
+        /**
+         * Used for instances of {@link ThrowsTree}
+         * representing an @exception tag.
+         */
+        EXCEPTION("exception"),
+
+        /**
+         * Used for instances of {@link IdentifierTree}
+         * representing an identifier.
+         */
+        IDENTIFIER,
+
+        /**
+         * Used for instances of {@link InheritDocTree}
+         * representing an @inheritDoc tag.
+         */
+        INHERIT_DOC("inheritDoc"),
+
+        /**
+         * Used for instances of {@link LinkTree}
+         * representing an @link tag.
+         */
+        LINK("link"),
+
+        /**
+         * Used for instances of {@link LinkTree}
+         * representing an @linkplain tag.
+         */
+        LINK_PLAIN("linkplain"),
+
+        /**
+         * Used for instances of {@link LiteralTree}
+         * representing an @literal tag.
+         */
+        LITERAL("literal"),
+
+        /**
+         * Used for instances of {@link ParamTree}
+         * representing an @param tag.
+         */
+        PARAM("param"),
+
+        /**
+         * Used for instances of {@link ReferenceTree}
+         * representing a reference to a element in the
+         * Java programming language.
+         */
+        REFERENCE,
+
+        /**
+         * Used for instances of {@link ReturnTree}
+         * representing an @return tag.
+         */
+        RETURN("return"),
+
+        /**
+         * Used for instances of {@link SeeTree}
+         * representing an @see tag.
+         */
+        SEE("see"),
+
+        /**
+         * Used for instances of {@link SerialTree}
+         * representing an @serial tag.
+         */
+        SERIAL("serial"),
+
+        /**
+         * Used for instances of {@link SerialDataTree}
+         * representing an @serialData tag.
+         */
+        SERIAL_DATA("serialData"),
+
+        /**
+         * Used for instances of {@link SerialFieldTree}
+         * representing an @serialField tag.
+         */
+        SERIAL_FIELD("serialField"),
+
+        /**
+         * Used for instances of {@link SinceTree}
+         * representing an @since tag.
+         */
+        SINCE("since"),
+
+        /**
+         * Used for instances of {@link EndElementTree}
+         * representing the start of an HTML element.
+         */
+        START_ELEMENT,
+
+        /**
+         * Used for instances of {@link TextTree}
+         * representing some documentation text.
+         */
+        TEXT,
+
+        /**
+         * Used for instances of {@link ThrowsTree}
+         * representing an @throws tag.
+         */
+        THROWS("throws"),
+
+        /**
+         * Used for instances of {@link UnknownBlockTagTree}
+         * representing an unknown block tag.
+         */
+        UNKNOWN_BLOCK_TAG,
+
+        /**
+         * Used for instances of {@link UnknownInlineTagTree}
+         * representing an unknown inline tag.
+         */
+        UNKNOWN_INLINE_TAG,
+
+        /**
+         * Used for instances of {@link ValueTree}
+         * representing an @value tag.
+         */
+        VALUE("value"),
+
+        /**
+         * Used for instances of {@link VersionTree}
+         * representing an @version tag.
+         */
+        VERSION("version"),
+
+        /**
+         * An implementation-reserved node. This is the not the node
+         * you are looking for.
+         */
+        OTHER;
+
+        public final String tagName;
+
+        Kind() {
+            tagName = null;
+        }
+
+        Kind(String tagName) {
+            this.tagName = tagName;
+        }
+    };
+
+    /**
+     * Gets the kind of this tree.
+     *
+     * @return the kind of this tree.
+     */
+    Kind getKind();
+
+    /**
+     * Accept method used to implement the visitor pattern.  The
+     * visitor pattern is used to implement operations on trees.
+     *
+     * @param <R> result type of this operation.
+     * @param <D> type of additional data.
+     */
+    <R, D> R accept(DocTreeVisitor<R,D> visitor, D data);
+}

langtools/src/share/classes/com/sun/source/doctree/DocTreeVisitor.java

@@ -0,0 +1,87 @@
+/*
+ * Copyright (c) 2011, 2012, 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;
+
+
+/**
+ * A visitor of trees, in the style of the visitor design pattern.
+ * Classes implementing this interface are used to operate
+ * on a tree when the kind of tree is unknown at compile time.
+ * When a visitor is passed to an tree's {@link DocTree#accept
+ * accept} method, the <tt>visit<i>XYZ</i></tt> method most applicable
+ * to that tree is invoked.
+ *
+ * <p> Classes implementing this interface may or may not throw a
+ * {@code NullPointerException} if the additional parameter {@code p}
+ * is {@code null}; see documentation of the implementing class for
+ * details.
+ *
+ * <p> <b>WARNING:</b> It is possible that methods will be added to
+ * this interface to accommodate new, currently unknown, doc comment
+ * structures added to future versions of the Java&trade; programming
+ * language.  Therefore, visitor classes directly implementing this
+ * interface may be source incompatible with future versions of the
+ * platform.
+ *
+ * @param <R> the return type of this visitor's methods.  Use {@link
+ *            Void} for visitors that do not need to return results.
+ * @param <P> the type of the additional parameter to this visitor's
+ *            methods.  Use {@code Void} for visitors that do not need an
+ *            additional parameter.
+ *
+ * @since 1.8
+ */
+public interface DocTreeVisitor<R,P> {
+    R visitAttribute(AttributeTree node, P p);
+    R visitAuthor(AuthorTree node, P p);
+    R visitComment(CommentTree node, P p);
+    R visitDeprecated(DeprecatedTree node, P p);
+    R visitDocComment(DocCommentTree node, P p);
+    R visitDocRoot(DocRootTree node, P p);
+    R visitEndElement(EndElementTree node, P p);
+    R visitEntity(EntityTree node, P p);
+    R visitErroneous(ErroneousTree node, P p);
+    R visitIdentifier(IdentifierTree node, P p);
+    R visitInheritDoc(InheritDocTree node, P p);
+    R visitLink(LinkTree node, P p);
+    R visitLiteral(LiteralTree node, P p);
+    R visitParam(ParamTree node, P p);
+    R visitReference(ReferenceTree node, P p);
+    R visitReturn(ReturnTree node, P p);
+    R visitSee(SeeTree node, P p);
+    R visitSerial(SerialTree node, P p);
+    R visitSerialData(SerialDataTree node, P p);
+    R visitSerialField(SerialFieldTree node, P p);
+    R visitSince(SinceTree node, P p);
+    R visitStartElement(StartElementTree node, P p);
+    R visitText(TextTree node, P p);
+    R visitThrows(ThrowsTree node, P p);
+    R visitUnknownBlockTag(UnknownBlockTagTree node, P p);
+    R visitUnknownInlineTag(UnknownInlineTagTree node, P p);
+    R visitValue(ValueTree node, P p);
+    R visitVersion(VersionTree node, P p);
+    R visitOther(DocTree node, P p);
+}

langtools/src/share/classes/com/sun/source/doctree/EndElementTree.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright (c) 2011, 2012, 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 javax.lang.model.element.Name;
+
+/**
+ * A tree node for the end of an HTML element.
+ *
+ * <p>
+ * &lt;/ name &gt;
+ *
+ * @since 1.8
+ */
+public interface EndElementTree extends DocTree {
+    Name getName();
+}

langtools/src/share/classes/com/sun/source/doctree/EntityTree.java

@@ -0,0 +1,41 @@
+/*
+ * Copyright (c) 2011, 2012, 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 javax.lang.model.element.Name;
+
+
+/**
+ * A tree node for an HTML entity.
+ *
+ * <p>
+ * &amp; name ;
+ *
+ * @since 1.8
+ */
+public interface EntityTree extends DocTree {
+    Name getName();
+}

langtools/src/share/classes/com/sun/source/doctree/ErroneousTree.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright (c) 2011, 2012, 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 javax.tools.Diagnostic;
+import javax.tools.JavaFileObject;
+
+/**
+ * A tree node to stand in for a malformed text
+ *
+ * @since 1.8
+ */
+public interface ErroneousTree extends TextTree {
+    /**
+     * Gets a diagnostic object giving details about
+     * the reason the body text is in error.
+     *
+     * @return a diagnostic
+     */
+    Diagnostic<JavaFileObject> getDiagnostic();
+}

langtools/src/share/classes/com/sun/source/doctree/IdentifierTree.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright (c) 2011, 2012, 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 javax.lang.model.element.Name;
+
+/**
+ * An identifier in a documentation comment.
+ *
+ * <p>
+ * name
+ *
+ * @since 1.8
+ */
+public interface IdentifierTree extends DocTree {
+    Name getName();
+}

langtools/src/share/classes/com/sun/source/doctree/InheritDocTree.java

@@ -0,0 +1,37 @@
+/*
+ * Copyright (c) 2011, 2012, 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;
+
+/**
+ *
+ * A tree node for an @inheritDoc inline tag.
+ *
+ * <p>
+ * {&#064;inheritDoc}
+ *
+ * @since 1.8
+ */
+public interface InheritDocTree extends InlineTagTree { }

langtools/src/share/classes/com/sun/source/doctree/InlineTagTree.java

@@ -0,0 +1,36 @@
+/*
+ * Copyright (c) 2011, 2012, 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;
+
+/**
+ * A tree node used as the base class for the different types of
+ * inline tags.
+ *
+ * @since 1.8
+ */
+public interface InlineTagTree extends DocTree {
+    String getTagName();
+}

langtools/src/share/classes/com/sun/source/doctree/LinkTree.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright (c) 2011, 2012, 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 @link or @linkplain inline tag.
+ *
+ * <p>
+ * {&#064;link reference label} <br>
+ * {&#064;linkplain reference label }
+ *
+ * @since 1.8
+ */
+public interface LinkTree extends InlineTagTree {
+    ReferenceTree getReference();
+    List<? extends DocTree> getLabel();
+}

langtools/src/share/classes/com/sun/source/doctree/LiteralTree.java

@@ -0,0 +1,39 @@
+/*
+ * Copyright (c) 2011, 2012, 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;
+
+/**
+ *
+ * A tree node for an @literal or @code inline tag.
+ *
+ * <p>
+ * {&#064;literal text}
+ *
+ * @since 1.8
+ */
+public interface LiteralTree extends InlineTagTree {
+    TextTree getBody();
+}

langtools/src/share/classes/com/sun/source/doctree/ParamTree.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright (c) 2011, 2012, 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 @param block tag.
+ *
+ * <p>
+ * &#064;param parameter-name description
+ *
+ * @since 1.8
+ */
+public interface ParamTree extends BlockTagTree {
+    boolean isTypeParameter();
+    IdentifierTree getName();
+    List<? extends DocTree> getDescription();
+}

langtools/src/share/classes/com/sun/source/doctree/ReferenceTree.java

@@ -0,0 +1,38 @@
+/*
+ * Copyright (c) 2011, 2012, 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;
+
+/**
+ * A tree node to a reference to a Java language element.
+ *
+ * <p>
+ * package.class#field
+ *
+ * @since 1.8
+ */
+public interface ReferenceTree extends DocTree {
+    String getSignature();
+}

langtools/src/share/classes/com/sun/source/doctree/ReturnTree.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright (c) 2011, 2012, 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 @return block tag.
+ *
+ * <p>
+ * &#064;return description
+ *
+ * @since 1.8
+ */
+public interface ReturnTree extends BlockTagTree {
+    List<? extends DocTree> getDescription();
+}

langtools/src/share/classes/com/sun/source/doctree/SeeTree.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright (c) 2011, 2012, 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 @see block tag.
+ *
+ * <p>
+ * &#064;see "string" <br>
+ * &#064;see &lt;a href="URL#value"&gt; label &lt;/a&gt; <br>
+ * &#064;see reference
+ *
+ * @since 1.8
+ */
+public interface SeeTree extends BlockTagTree {
+    List<? extends DocTree> getReference();
+}

langtools/src/share/classes/com/sun/source/doctree/SerialDataTree.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright (c) 2011, 2012, 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 @serialData block tag.
+ *
+ * <p>
+ * &#064;serialData data-description
+ *
+ * @since 1.8
+ */
+public interface SerialDataTree extends BlockTagTree {
+    List<? extends DocTree> getDescription();
+}

langtools/src/share/classes/com/sun/source/doctree/SerialFieldTree.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright (c) 2011, 2012, 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 @serialData block tag.
+ *
+ * <p>
+ * &#064;serialField field-name field-type field-description
+ *
+ * @since 1.8
+ */
+public interface SerialFieldTree extends BlockTagTree {
+    IdentifierTree getName();
+    ReferenceTree getType();
+    List<? extends DocTree> getDescription();
+}

langtools/src/share/classes/com/sun/source/doctree/SerialTree.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright (c) 2011, 2012, 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 @serial block tag.
+ *
+ * <p>
+ * &#064;serial field-description | include | exclude
+ *
+ * @since 1.8
+ */
+public interface SerialTree extends BlockTagTree {
+    List<? extends DocTree> getDescription();
+}

langtools/src/share/classes/com/sun/source/doctree/SinceTree.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright (c) 2011, 2012, 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 @since block tag.
+ *
+ * <p>
+ * &#064;since since-text
+ *
+ * @since 1.8
+ */
+public interface SinceTree extends BlockTagTree {
+    List<? extends DocTree> getBody();
+}

langtools/src/share/classes/com/sun/source/doctree/StartElementTree.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright (c) 2011, 2012, 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;
+import javax.lang.model.element.Name;
+
+/**
+ * A tree node for the start of an HTML element.
+ *
+ * <p>
+ * &lt; name [attributes] [/]&gt;
+ *
+ * @since 1.8
+ */
+public interface StartElementTree extends DocTree {
+    Name getName();
+    List<? extends DocTree> getAttributes();
+    boolean isSelfClosing();
+}

langtools/src/share/classes/com/sun/source/doctree/TextTree.java

@@ -0,0 +1,35 @@
+/*
+ * Copyright (c) 2011, 2012, 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;
+
+/**
+ * A tree node for plain text.
+ *
+ * @since 1.8
+ */
+public interface TextTree extends DocTree {
+    String getBody();
+}

langtools/src/share/classes/com/sun/source/doctree/ThrowsTree.java

@@ -0,0 +1,44 @@
+/*
+ * Copyright (c) 2011, 2012, 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 @exception or @throws block tag.
+ * @exception is a synonym for @throws.
+ *
+ * <p>
+ * &#064;exception class-name description <br>
+ * &#064;throws class-name description
+ *
+ * @since 1.8
+ */
+public interface ThrowsTree extends BlockTagTree {
+    ReferenceTree getExceptionName();
+    List<? extends DocTree> getDescription();
+}

langtools/src/share/classes/com/sun/source/doctree/UnknownBlockTagTree.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright (c) 2011, 2012, 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 unrecognized inline tag.
+ *
+ * <p>
+ * &#064;name content
+ *
+ * @since 1.8
+ *
+ */
+public interface UnknownBlockTagTree extends BlockTagTree {
+    List<? extends DocTree> getContent();
+}

langtools/src/share/classes/com/sun/source/doctree/UnknownInlineTagTree.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright (c) 2011, 2012, 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 unrecognized inline tag.
+ *
+ * <p>
+ * {&#064;name content}
+ *
+ * @since 1.8
+ *
+ */
+public interface UnknownInlineTagTree extends InlineTagTree {
+    List<? extends DocTree> getContent();
+}

langtools/src/share/classes/com/sun/source/doctree/ValueTree.java

@@ -0,0 +1,38 @@
+/*
+ * Copyright (c) 2011, 2012, 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;
+
+/**
+ * A tree node for an @value inline tag.
+ *
+ * <p>
+ * { &#064;value reference }
+ *
+ * @since 1.8
+ */
+public interface ValueTree extends InlineTagTree {
+    ReferenceTree getReference();
+}

langtools/src/share/classes/com/sun/source/doctree/VersionTree.java

@@ -0,0 +1,41 @@
+/*
+ * Copyright (c) 2011, 2012, 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 @version block tag.
+ *
+ * <p>
+ * &#064;version version-text
+ *
+ * @since 1.8
+ */
+public interface VersionTree extends BlockTagTree {
+    List<? extends DocTree> getBody();
+}

langtools/src/share/classes/com/sun/source/doctree/package-info.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright (c) 2011, 2012, 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.
+ */
+
+/**
+ * Provides interfaces to represent documentation comments as abstract syntax
+ * trees (AST).
+ *
+ * @author Jonathan Gibbons
+ * @since 1.8
+ * @see <a href="http://download.oracle.com/javase/6/docs/technotes/tools/solaris/javadoc.html#javadoctags">http://download.oracle.com/javase/6/docs/technotes/tools/solaris/javadoc.html#javadoctags</a>
+ */
+package com.sun.source.doctree;

langtools/src/share/classes/com/sun/source/tree/Tree.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2012, 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
@@ -610,7 +610,7 @@ public interface Tree {
      * visitor pattern is used to implement operations on trees.
      *
      * @param <R> result type of this operation.
-     * @param <D> type of additonal data.
+     * @param <D> type of additional data.
      */
     <R,D> R accept(TreeVisitor<R,D> visitor, D data);
 }

langtools/src/share/classes/com/sun/source/util/DocTreeScanner.java

@@ -0,0 +1,273 @@
+/*
+ * Copyright (c) 2011, 2012, 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.*;
+
+
+/**
+ * A TreeVisitor that visits all the child tree nodes.
+ * To visit nodes of a particular type, just override the
+ * corresponding visitXYZ method.
+ * Inside your method, call super.visitXYZ to visit descendant
+ * nodes.
+ *
+ * <p>The default implementation of the visitXYZ methods will determine
+ * a result as follows:
+ * <ul>
+ * <li>If the node being visited has no children, the result will be null.
+ * <li>If the node being visited has one child, the result will be the
+ * result of calling {@code scan} on that child. The child may be a simple node
+ * or itself a list of nodes.
+ * <li> If the node being visited has more than one child, the result will
+ * be determined by calling {@code scan} each child in turn, and then combining the
+ * result of each scan after the first with the cumulative result
+ * so far, as determined by the {@link #reduce} method. Each child may be either
+ * a simple node of a list of nodes. The default behavior of the {@code reduce}
+ * method is such that the result of the visitXYZ method will be the result of
+ * the last child scanned.
+ * </ul>
+ *
+ * <p>Here is an example to count the number of erroneous nodes in a tree:
+ * <pre>
+ *   class CountErrors extends DocTreeScanner<Integer,Void> {
+ *      {@literal @}Override
+ *      public Integer visitErroneous(ErroneousTree node, Void p) {
+ *          return 1;
+ *      }
+ *      {@literal @}Override
+ *      public Integer reduce(Integer r1, Integer r2) {
+ *          return (r1 == null ? 0 : r1) + (r2 == null ? 0 : r2);
+ *      }
+ *   }
+ * </pre>
+ *
+ * @since 1.8
+ */
+public class DocTreeScanner<R,P> implements DocTreeVisitor<R,P> {
+
+    /**
+     * Scan a single node.
+     */
+    public R scan(DocTree node, P p) {
+        return (node == null) ? null : node.accept(this, p);
+    }
+
+    private R scanAndReduce(DocTree node, P p, R r) {
+        return reduce(scan(node, p), r);
+    }
+
+    /**
+     * Scan a list of nodes.
+     */
+    public R scan(Iterable<? extends DocTree> nodes, P p) {
+        R r = null;
+        if (nodes != null) {
+            boolean first = true;
+            for (DocTree node : nodes) {
+                r = (first ? scan(node, p) : scanAndReduce(node, p, r));
+                first = false;
+            }
+        }
+        return r;
+    }
+
+    private R scanAndReduce(Iterable<? extends DocTree> nodes, P p, R r) {
+        return reduce(scan(nodes, p), r);
+    }
+
+    /**
+     * Reduces two results into a combined result.
+     * The default implementation is to return the first parameter.
+     * The general contract of the method is that it may take any action whatsoever.
+     */
+    public R reduce(R r1, R r2) {
+        return r1;
+    }
+
+
+/* ***************************************************************************
+ * Visitor methods
+ ****************************************************************************/
+
+    @Override
+    public R visitAttribute(AttributeTree node, P p) {
+        return null;
+    }
+
+    @Override
+    public R visitAuthor(AuthorTree node, P p) {
+        return scan(node.getName(), p);
+    }
+
+    @Override
+    public R visitComment(CommentTree node, P p) {
+        return null;
+    }
+
+    @Override
+    public R visitDeprecated(DeprecatedTree node, P p) {
+        return scan(node.getBody(), p);
+    }
+
+    @Override
+    public R visitDocComment(DocCommentTree node, P p) {
+        R r = scan(node.getFirstSentence(), p);
+        r = scanAndReduce(node.getBody(), p, r);
+        r = scanAndReduce(node.getBlockTags(), p, r);
+        return r;
+    }
+
+    @Override
+    public R visitDocRoot(DocRootTree node, P p) {
+        return null;
+    }
+
+    @Override
+    public R visitEndElement(EndElementTree node, P p) {
+        return null;
+    }
+
+    @Override
+    public R visitEntity(EntityTree node, P p) {
+        return null;
+    }
+
+    @Override
+    public R visitErroneous(ErroneousTree node, P p) {
+        return null;
+    }
+
+    @Override
+    public R visitIdentifier(IdentifierTree node, P p) {
+        return null;
+    }
+
+    @Override
+    public R visitInheritDoc(InheritDocTree node, P p) {
+        return null;
+    }
+
+    @Override
+    public R visitLink(LinkTree node, P p) {
+        R r = scan(node.getReference(), p);
+        r = scanAndReduce(node.getLabel(), p, r);
+        return r;
+    }
+
+    @Override
+    public R visitLiteral(LiteralTree node, P p) {
+        return null;
+    }
+
+    @Override
+    public R visitParam(ParamTree node, P p) {
+        R r = scan(node.getName(), p);
+        r = scanAndReduce(node.getDescription(), p, r);
+        return r;
+    }
+
+    @Override
+    public R visitReference(ReferenceTree node, P p) {
+        return null;
+    }
+
+    @Override
+    public R visitReturn(ReturnTree node, P p) {
+        return scan(node.getDescription(), p);
+    }
+
+    @Override
+    public R visitSee(SeeTree node, P p) {
+        return scan(node.getReference(), p);
+    }
+
+    @Override
+    public R visitSerial(SerialTree node, P p) {
+        return scan(node.getDescription(), p);
+    }
+
+    @Override
+    public R visitSerialData(SerialDataTree node, P p) {
+        return scan(node.getDescription(), p);
+    }
+
+    @Override
+    public R visitSerialField(SerialFieldTree node, P p) {
+        R r = scan(node.getName(), p);
+        r = scanAndReduce(node.getType(), p, r);
+        r = scanAndReduce(node.getDescription(), p, r);
+        return r;
+    }
+
+    @Override
+    public R visitSince(SinceTree node, P p) {
+        return scan(node.getBody(), p);
+    }
+
+    @Override
+    public R visitStartElement(StartElementTree node, P p) {
+        return scan(node.getAttributes(), p);
+    }
+
+    @Override
+    public R visitText(TextTree node, P p) {
+        return null;
+    }
+
+    @Override
+    public R visitThrows(ThrowsTree node, P p) {
+        R r = scan(node.getExceptionName(), p);
+        r = scanAndReduce(node.getDescription(), p, r);
+        return r;
+    }
+
+    @Override
+    public R visitUnknownBlockTag(UnknownBlockTagTree node, P p) {
+        return scan(node.getContent(), p);
+    }
+
+    @Override
+    public R visitUnknownInlineTag(UnknownInlineTagTree node, P p) {
+        return scan(node.getContent(), p);
+    }
+
+    @Override
+    public R visitValue(ValueTree node, P p) {
+        return scan(node.getReference(), p);
+    }
+
+    @Override
+    public R visitVersion(VersionTree node, P p) {
+        return scan(node.getBody(), p);
+    }
+
+    @Override
+    public R visitOther(DocTree node, P p) {
+        return null;
+    }
+
+}

langtools/src/share/classes/com/sun/source/util/DocTrees.java

@@ -0,0 +1,89 @@
+/*
+ * Copyright (c) 2011, 2012, 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 javax.annotation.processing.ProcessingEnvironment;
+import javax.lang.model.element.Element;
+import javax.tools.JavaCompiler.CompilationTask;
+
+import com.sun.source.doctree.DocCommentTree;
+import com.sun.source.doctree.ReferenceTree;
+import javax.tools.Diagnostic;
+
+/**
+ * Provides access to syntax trees for doc comments.
+ *
+ * @since 1.8
+ */
+public abstract class DocTrees extends Trees {
+    /**
+     * Gets a DocTrees object for a given CompilationTask.
+     * @param task the compilation task for which to get the Trees object
+     * @throws IllegalArgumentException if the task does not support the Trees API.
+     */
+    public static DocTrees instance(CompilationTask task) {
+        if (!task.getClass().getName().equals("com.sun.tools.javac.api.JavacTaskImpl"))
+            throw new IllegalArgumentException();
+        return (DocTrees) getJavacTrees(CompilationTask.class, task);
+    }
+
+    /**
+     * Gets a DocTrees object for a given ProcessingEnvironment.
+     * @param env the processing environment for which to get the Trees object
+     * @throws IllegalArgumentException if the env does not support the Trees API.
+     */
+    public static DocTrees instance(ProcessingEnvironment env) {
+        if (!env.getClass().getName().equals("com.sun.tools.javac.processing.JavacProcessingEnvironment"))
+            throw new IllegalArgumentException();
+        return (DocTrees) getJavacTrees(ProcessingEnvironment.class, env);
+    }
+
+    /**
+     * Gets the doc comment tree, if any, for the Tree node identified by a given TreePath.
+     * Returns null if no doc comment was found.
+     */
+    public abstract DocCommentTree getDocCommentTree(TreePath path);
+
+    /**
+     * Gets the language model element referred to by a ReferenceTree that
+     * appears on the declaration identified by the given path.
+     */
+    public abstract Element getElement(TreePath path, ReferenceTree reference);
+
+    /**
+     * Prints a message of the specified kind at the location of the
+     * tree within the provided compilation unit
+     *
+     * @param kind the kind of message
+     * @param msg  the message, or an empty string if none
+     * @param t    the tree to use as a position hint
+     * @param root the compilation unit that contains tree
+     */
+    public abstract void printMessage(Diagnostic.Kind kind, CharSequence msg,
+            com.sun.source.doctree.DocTree t,
+            com.sun.source.doctree.DocCommentTree c,
+            com.sun.source.tree.CompilationUnitTree root);
+}

langtools/src/share/classes/com/sun/source/util/SimpleDocTreeVisitor.java

@@ -0,0 +1,179 @@
+/*
+ * Copyright (c) 2005, 2012, 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.*;
+
+/**
+ * A simple visitor for tree nodes.
+ *
+ * @since 1.8
+ */
+public class SimpleDocTreeVisitor<R,P> implements DocTreeVisitor<R, P> {
+    protected final R DEFAULT_VALUE;
+
+    protected SimpleDocTreeVisitor() {
+        DEFAULT_VALUE = null;
+    }
+
+    protected SimpleDocTreeVisitor(R defaultValue) {
+        DEFAULT_VALUE = defaultValue;
+    }
+
+    protected R defaultAction(DocTree node, P p) {
+        return DEFAULT_VALUE;
+    }
+
+    public final R visit(DocTree node, P p) {
+        return (node == null) ? null : node.accept(this, p);
+    }
+
+    public final R visit(Iterable<? extends DocTree> nodes, P p) {
+        R r = null;
+        if (nodes != null) {
+            for (DocTree node : nodes)
+                r = visit(node, p);
+        }
+        return r;
+    }
+
+    public R visitAttribute(AttributeTree node, P p) {
+        return defaultAction(node, p);
+    }
+
+    public R visitAuthor(AuthorTree node, P p) {
+        return defaultAction(node, p);
+    }
+
+    public R visitComment(CommentTree node, P p) {
+        return defaultAction(node, p);
+    }
+
+    public R visitDeprecated(DeprecatedTree node, P p) {
+        return defaultAction(node, p);
+    }
+
+    public R visitDocComment(DocCommentTree node, P p) {
+        return defaultAction(node, p);
+    }
+
+    public R visitDocRoot(DocRootTree node, P p) {
+        return defaultAction(node, p);
+    }
+
+    public R visitEndElement(EndElementTree node, P p) {
+        return defaultAction(node, p);
+    }
+
+    public R visitEntity(EntityTree node, P p) {
+        return defaultAction(node, p);
+    }
+
+    public R visitErroneous(ErroneousTree node, P p) {
+        return defaultAction(node, p);
+    }
+
+    public R visitIdentifier(IdentifierTree node, P p) {
+        return defaultAction(node, p);
+    }
+
+    public R visitInheritDoc(InheritDocTree node, P p) {
+        return defaultAction(node, p);
+    }
+
+    public R visitLink(LinkTree node, P p) {
+        return defaultAction(node, p);
+    }
+
+    public R visitLiteral(LiteralTree node, P p) {
+        return defaultAction(node, p);
+    }
+
+    public R visitParam(ParamTree node, P p) {
+        return defaultAction(node, p);
+    }
+
+    public R visitReference(ReferenceTree node, P p) {
+        return defaultAction(node, p);
+    }
+
+    public R visitReturn(ReturnTree node, P p) {
+        return defaultAction(node, p);
+    }
+
+    public R visitSee(SeeTree node, P p) {
+        return defaultAction(node, p);
+    }
+
+    public R visitSerial(SerialTree node, P p) {
+        return defaultAction(node, p);
+    }
+
+    public R visitSerialData(SerialDataTree node, P p) {
+        return defaultAction(node, p);
+    }
+
+    public R visitSerialField(SerialFieldTree node, P p) {
+        return defaultAction(node, p);
+    }
+
+    public R visitSince(SinceTree node, P p) {
+        return defaultAction(node, p);
+    }
+
+    public R visitStartElement(StartElementTree node, P p) {
+        return defaultAction(node, p);
+    }
+
+    public R visitText(TextTree node, P p) {
+        return defaultAction(node, p);
+    }
+
+    public R visitThrows(ThrowsTree node, P p) {
+        return defaultAction(node, p);
+    }
+
+    public R visitUnknownBlockTag(UnknownBlockTagTree node, P p) {
+        return defaultAction(node, p);
+    }
+
+    public R visitUnknownInlineTag(UnknownInlineTagTree node, P p) {
+        return defaultAction(node, p);
+    }
+
+    public R visitValue(ValueTree node, P p) {
+        return defaultAction(node, p);
+    }
+
+    public R visitVersion(VersionTree node, P p) {
+        return defaultAction(node, p);
+    }
+
+    public R visitOther(DocTree node, P p) {
+        return defaultAction(node, p);
+    }
+
+}

langtools/src/share/classes/com/sun/source/util/Trees.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2012, 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
@@ -26,6 +26,7 @@
 package com.sun.source.util;
 
 import java.lang.reflect.Method;
+
 import javax.annotation.processing.ProcessingEnvironment;
 import javax.lang.model.element.AnnotationMirror;
 import javax.lang.model.element.AnnotationValue;
@@ -73,7 +74,7 @@ public abstract class Trees {
         return getJavacTrees(ProcessingEnvironment.class, env);
     }
 
-    private static Trees getJavacTrees(Class<?> argType, Object arg) {
+    static Trees getJavacTrees(Class<?> argType, Object arg) {
         try {
             ClassLoader cl = arg.getClass().getClassLoader();
             Class<?> c = Class.forName("com.sun.tools.javac.api.JavacTrees", false, cl);
@@ -168,6 +169,7 @@ public abstract class Trees {
     /**
      * Gets the doc comment, if any, for the Tree node identified by a given TreePath.
      * Returns null if no doc comment was found.
+     * @see DocTrees#getDocCommentTree(TreePath)
      */
     public abstract String getDocComment(TreePath path);
 

langtools/src/share/classes/com/sun/tools/javac/api/JavacTrees.java

@@ -26,6 +26,8 @@
 package com.sun.tools.javac.api;
 
 import java.io.IOException;
+import java.util.HashSet;
+import java.util.Set;
 
 import javax.annotation.processing.ProcessingEnvironment;
 import javax.lang.model.element.AnnotationMirror;
@@ -40,19 +42,31 @@ import javax.tools.Diagnostic;
 import javax.tools.JavaCompiler;
 import javax.tools.JavaFileObject;
 
+import com.sun.source.doctree.DocCommentTree;
+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.DocTrees;
 import com.sun.source.util.JavacTask;
 import com.sun.source.util.SourcePositions;
 import com.sun.source.util.TreePath;
-import com.sun.source.util.Trees;
 import com.sun.tools.javac.code.Flags;
+import com.sun.tools.javac.code.Kinds;
 import com.sun.tools.javac.code.Symbol;
 import com.sun.tools.javac.code.Symbol.ClassSymbol;
+import com.sun.tools.javac.code.Symbol.MethodSymbol;
+import com.sun.tools.javac.code.Symbol.PackageSymbol;
 import com.sun.tools.javac.code.Symbol.TypeSymbol;
+import com.sun.tools.javac.code.Symbol.VarSymbol;
+import com.sun.tools.javac.code.Type;
+import com.sun.tools.javac.code.Type.ArrayType;
+import com.sun.tools.javac.code.Type.ClassType;
+import com.sun.tools.javac.code.Type.ErrorType;
 import com.sun.tools.javac.code.Type.UnionClassType;
+import com.sun.tools.javac.code.Types;
+import com.sun.tools.javac.code.Types.TypeRelation;
 import com.sun.tools.javac.comp.Attr;
 import com.sun.tools.javac.comp.AttrContext;
 import com.sun.tools.javac.comp.Enter;
@@ -61,6 +75,9 @@ import com.sun.tools.javac.comp.MemberEnter;
 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.DCDocComment;
+import com.sun.tools.javac.tree.DCTree.DCReference;
 import com.sun.tools.javac.tree.EndPosTable;
 import com.sun.tools.javac.tree.JCTree;
 import com.sun.tools.javac.tree.JCTree.*;
@@ -71,8 +88,12 @@ import com.sun.tools.javac.util.Assert;
 import com.sun.tools.javac.util.Context;
 import com.sun.tools.javac.util.JCDiagnostic;
 import com.sun.tools.javac.util.List;
+import com.sun.tools.javac.util.ListBuffer;
 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 static com.sun.tools.javac.code.TypeTag.*;
 
 /**
  * Provides an implementation of Trees.
@@ -84,7 +105,7 @@ import com.sun.tools.javac.util.Pair;
  *
  * @author Peter von der Ahé
  */
-public class JavacTrees extends Trees {
+public class JavacTrees extends DocTrees {
 
     // in a world of a single context per compilation, these would all be final
     private Resolve resolve;
@@ -95,6 +116,8 @@ public class JavacTrees extends Trees {
     private TreeMaker treeMaker;
     private JavacElements elements;
     private JavacTaskImpl javacTaskImpl;
+    private Names names;
+    private Types types;
 
     // called reflectively from Trees.instance(CompilationTask task)
     public static JavacTrees instance(JavaCompiler.CompilationTask task) {
@@ -134,6 +157,8 @@ public class JavacTrees extends Trees {
         resolve = Resolve.instance(context);
         treeMaker = TreeMaker.instance(context);
         memberEnter = MemberEnter.instance(context);
+        names = Names.instance(context);
+        types = Types.instance(context);
 
         JavacTask t = context.get(JavacTask.class);
         if (t instanceof JavacTaskImpl)
@@ -229,6 +254,324 @@ public class JavacTrees extends Trees {
         return sym;
     }
 
+    @Override
+    public Element getElement(TreePath path, ReferenceTree reference) {
+        if (!(reference instanceof DCReference))
+            return null;
+        DCReference ref = (DCReference) reference;
+
+        Env<AttrContext> env = getAttrContext(path);
+
+        Log.DeferredDiagnosticHandler deferredDiagnosticHandler =
+                new Log.DeferredDiagnosticHandler(log);
+        try {
+            final ClassSymbol tsym;
+            final Name memberName;
+            if (ref.qualifierExpression == null) {
+                tsym = env.enclClass.sym;
+                memberName = ref.memberName;
+            } else {
+                // See if the qualifierExpression is a type or package name.
+                // javac does not provide the exact method required, so
+                // we first check if qualifierExpression identifies a type,
+                // and if not, then we check to see if it identifies a package.
+                Type t = attr.attribType(ref.qualifierExpression, env);
+                if (t.isErroneous()) {
+                    if (ref.memberName == null) {
+                        // Attr/Resolve assume packages exist and create symbols as needed
+                        // so use getPackageElement to restrict search to existing packages
+                        PackageSymbol pck = elements.getPackageElement(ref.qualifierExpression.toString());
+                        if (pck != null) {
+                            return pck;
+                        } else if (ref.qualifierExpression.hasTag(JCTree.Tag.IDENT)) {
+                            // fixup:  allow "identifier" instead of "#identifier"
+                            // for compatibility with javadoc
+                            tsym = env.enclClass.sym;
+                            memberName = ((JCIdent) ref.qualifierExpression).name;
+                        } else
+                            return null;
+                    } else {
+                        return null;
+                    }
+                } else {
+                    tsym = (ClassSymbol) t.tsym;
+                    memberName = ref.memberName;
+                }
+            }
+
+            if (memberName == null)
+                return tsym;
+
+            final List<Type> paramTypes;
+            if (ref.paramTypes == null)
+                paramTypes = null;
+            else {
+                ListBuffer<Type> lb = new ListBuffer<Type>();
+                for (List<JCTree> l = ref.paramTypes; l.nonEmpty(); l = l.tail) {
+                    JCTree tree = l.head;
+                    Type t = attr.attribType(tree, env);
+                    lb.add(t);
+                }
+                paramTypes = lb.toList();
+            }
+
+            Symbol msym = (memberName == tsym.name)
+                    ? findConstructor(tsym, paramTypes)
+                    : findMethod(tsym, memberName, paramTypes);
+            if (paramTypes != null) {
+                // explicit (possibly empty) arg list given, so cannot be a field
+                return msym;
+            }
+
+            VarSymbol vsym = (ref.paramTypes != null) ? null : findField(tsym, memberName);
+            // prefer a field over a method with no parameters
+            if (vsym != null &&
+                    (msym == null ||
+                        types.isSubtypeUnchecked(vsym.enclClass().asType(), msym.enclClass().asType()))) {
+                return vsym;
+            } else {
+                return msym;
+            }
+        } finally {
+            log.popDiagnosticHandler(deferredDiagnosticHandler);
+        }
+    }
+
+    /** @see com.sun.tools.javadoc.ClassDocImpl#findField */
+    private VarSymbol findField(ClassSymbol tsym, Name fieldName) {
+        return searchField(tsym, fieldName, new HashSet<ClassSymbol>());
+    }
+
+    /** @see com.sun.tools.javadoc.ClassDocImpl#searchField */
+    private VarSymbol searchField(ClassSymbol tsym, Name fieldName, Set<ClassSymbol> searched) {
+        if (searched.contains(tsym)) {
+            return null;
+        }
+        searched.add(tsym);
+
+        for (com.sun.tools.javac.code.Scope.Entry e = tsym.members().lookup(fieldName);
+                e.scope != null; e = e.next()) {
+            if (e.sym.kind == Kinds.VAR) {
+                return (VarSymbol)e.sym;
+            }
+        }
+
+        //### If we found a VarSymbol above, but which did not pass
+        //### the modifier filter, we should return failure here!
+
+        ClassSymbol encl = tsym.owner.enclClass();
+        if (encl != null) {
+            VarSymbol vsym = searchField(encl, fieldName, searched);
+            if (vsym != null) {
+                return vsym;
+            }
+        }
+
+        // search superclass
+        Type superclass = tsym.getSuperclass();
+        if (superclass.tsym != null) {
+            VarSymbol vsym = searchField((ClassSymbol) superclass.tsym, fieldName, searched);
+            if (vsym != null) {
+                return vsym;
+            }
+        }
+
+        // search interfaces
+        List<Type> intfs = tsym.getInterfaces();
+        for (List<Type> l = intfs; l.nonEmpty(); l = l.tail) {
+            Type intf = l.head;
+            if (intf.isErroneous()) continue;
+            VarSymbol vsym = searchField((ClassSymbol) intf.tsym, fieldName, searched);
+            if (vsym != null) {
+                return vsym;
+            }
+        }
+
+        return null;
+    }
+
+    /** @see com.sun.tools.javadoc.ClassDocImpl#findConstructor */
+    MethodSymbol findConstructor(ClassSymbol tsym, List<Type> paramTypes) {
+        for (com.sun.tools.javac.code.Scope.Entry e = tsym.members().lookup(names.init);
+                e.scope != null; e = e.next()) {
+            if (e.sym.kind == Kinds.MTH) {
+                if (hasParameterTypes((MethodSymbol) e.sym, paramTypes)) {
+                    return (MethodSymbol) e.sym;
+                }
+            }
+        }
+        return null;
+    }
+
+    /** @see com.sun.tools.javadoc.ClassDocImpl#findMethod */
+    private MethodSymbol findMethod(ClassSymbol tsym, Name methodName, List<Type> paramTypes) {
+        return searchMethod(tsym, methodName, paramTypes, new HashSet<ClassSymbol>());
+    }
+
+    /** @see com.sun.tools.javadoc.ClassDocImpl#searchMethod */
+    private MethodSymbol searchMethod(ClassSymbol tsym, Name methodName,
+                                       List<Type> paramTypes, Set<ClassSymbol> searched) {
+        //### Note that this search is not necessarily what the compiler would do!
+
+        // do not match constructors
+        if (methodName == names.init)
+            return null;
+
+        if (searched.contains(tsym))
+            return null;
+        searched.add(tsym);
+
+        // search current class
+        com.sun.tools.javac.code.Scope.Entry e = tsym.members().lookup(methodName);
+
+        //### Using modifier filter here isn't really correct,
+        //### but emulates the old behavior.  Instead, we should
+        //### apply the normal rules of visibility and inheritance.
+
+        if (paramTypes == null) {
+            // If no parameters specified, we are allowed to return
+            // any method with a matching name.  In practice, the old
+            // code returned the first method, which is now the last!
+            // In order to provide textually identical results, we
+            // attempt to emulate the old behavior.
+            MethodSymbol lastFound = null;
+            for (; e.scope != null; e = e.next()) {
+                if (e.sym.kind == Kinds.MTH) {
+                    if (e.sym.name == methodName) {
+                        lastFound = (MethodSymbol)e.sym;
+                    }
+                }
+            }
+            if (lastFound != null) {
+                return lastFound;
+            }
+        } else {
+            for (; e.scope != null; e = e.next()) {
+                if (e.sym != null &&
+                    e.sym.kind == Kinds.MTH) {
+                    if (hasParameterTypes((MethodSymbol) e.sym, paramTypes)) {
+                        return (MethodSymbol) e.sym;
+                    }
+                }
+            }
+        }
+
+        //### If we found a MethodSymbol above, but which did not pass
+        //### the modifier filter, we should return failure here!
+
+        // search superclass
+        Type superclass = tsym.getSuperclass();
+        if (superclass.tsym != null) {
+            MethodSymbol msym = searchMethod((ClassSymbol) superclass.tsym, methodName, paramTypes, searched);
+            if (msym != null) {
+                return msym;
+            }
+        }
+
+        // search interfaces
+        List<Type> intfs = tsym.getInterfaces();
+        for (List<Type> l = intfs; l.nonEmpty(); l = l.tail) {
+            Type intf = l.head;
+            if (intf.isErroneous()) continue;
+            MethodSymbol msym = searchMethod((ClassSymbol) intf.tsym, methodName, paramTypes, searched);
+            if (msym != null) {
+                return msym;
+            }
+        }
+
+        // search enclosing class
+        ClassSymbol encl = tsym.owner.enclClass();
+        if (encl != null) {
+            MethodSymbol msym = searchMethod(encl, methodName, paramTypes, searched);
+            if (msym != null) {
+                return msym;
+            }
+        }
+
+        return null;
+    }
+
+    /** @see com.sun.tools.javadoc.ClassDocImpl */
+    private boolean hasParameterTypes(MethodSymbol method, List<Type> paramTypes) {
+        if (paramTypes == null)
+            return true;
+
+        if (method.params().size() != paramTypes.size())
+            return false;
+
+        List<Type> methodParamTypes = types.erasureRecursive(method.asType()).getParameterTypes();
+
+        return (Type.isErroneous(paramTypes))
+            ? fuzzyMatch(paramTypes, methodParamTypes)
+            : types.isSameTypes(paramTypes, methodParamTypes);
+    }
+
+    boolean fuzzyMatch(List<Type> paramTypes, List<Type> methodParamTypes) {
+        List<Type> l1 = paramTypes;
+        List<Type> l2 = methodParamTypes;
+        while (l1.nonEmpty()) {
+            if (!fuzzyMatch(l1.head, l2.head))
+                return false;
+            l1 = l1.tail;
+            l2 = l2.tail;
+        }
+        return true;
+    }
+
+    boolean fuzzyMatch(Type paramType, Type methodParamType) {
+        Boolean b = fuzzyMatcher.visit(paramType, methodParamType);
+        return (b == Boolean.TRUE);
+    }
+
+    TypeRelation fuzzyMatcher = new TypeRelation() {
+        @Override
+        public Boolean visitType(Type t, Type s) {
+            if (t == s)
+                return true;
+
+            if (s.isPartial())
+                return visit(s, t);
+
+            switch (t.getTag()) {
+            case BYTE: case CHAR: case SHORT: case INT: case LONG: case FLOAT:
+            case DOUBLE: case BOOLEAN: case VOID: case BOT: case NONE:
+                return t.getTag() == s.getTag();
+
+            default:
+                throw new AssertionError("fuzzyMatcher " + t.getTag());
+            }
+        }
+
+        @Override
+        public Boolean visitArrayType(ArrayType t, Type s) {
+            if (t == s)
+                return true;
+
+            if (s.isPartial())
+                return visit(s, t);
+
+            return s.getTag() == ARRAY
+                && visit(t.elemtype, types.elemtype(s));
+        }
+
+        @Override
+        public Boolean visitClassType(ClassType t, Type s) {
+            if (t == s)
+                return true;
+
+            if (s.isPartial())
+                return visit(s, t);
+
+            return t.tsym == s.tsym;
+        }
+
+        @Override
+        public Boolean visitErrorType(ErrorType t, Type s) {
+            return s.getTag() == CLASS
+                    && t.tsym.name == ((ClassType) s).tsym.name;
+        }
+    };
+
     public TypeMirror getTypeMirror(TreePath path) {
         Tree t = path.getLeaf();
         return ((JCTree)t).type;
@@ -250,6 +593,18 @@ public class JavacTrees extends Trees {
         return null;
     }
 
+    public DocCommentTree getDocCommentTree(TreePath path) {
+        CompilationUnitTree t = path.getCompilationUnit();
+        Tree leaf = path.getLeaf();
+        if (t instanceof JCTree.JCCompilationUnit && leaf instanceof JCTree) {
+            JCCompilationUnit cu = (JCCompilationUnit) t;
+            if (cu.docComments != null) {
+                return cu.docComments.getCommentTree((JCTree) leaf);
+            }
+        }
+        return null;
+    }
+
     public boolean isAccessible(Scope scope, TypeElement type) {
         if (scope instanceof JavacScope && type instanceof ClassSymbol) {
             Env<AttrContext> env = ((JavacScope) scope).env;
@@ -418,14 +773,27 @@ public class JavacTrees extends Trees {
     public void printMessage(Diagnostic.Kind kind, CharSequence msg,
             com.sun.source.tree.Tree t,
             com.sun.source.tree.CompilationUnitTree root) {
+        printMessage(kind, msg, ((JCTree) t).pos(), root);
+    }
+
+    public void printMessage(Diagnostic.Kind kind, CharSequence msg,
+            com.sun.source.doctree.DocTree t,
+            com.sun.source.doctree.DocCommentTree c,
+            com.sun.source.tree.CompilationUnitTree root) {
+        printMessage(kind, msg, ((DCTree) t).pos((DCDocComment) c), root);
+    }
+
+    private void printMessage(Diagnostic.Kind kind, CharSequence msg,
+            JCDiagnostic.DiagnosticPosition pos,
+            com.sun.source.tree.CompilationUnitTree root) {
         JavaFileObject oldSource = null;
         JavaFileObject newSource = null;
-        JCDiagnostic.DiagnosticPosition pos = null;
 
         newSource = root.getSourceFile();
-        if (newSource != null) {
+        if (newSource == null) {
+            pos = null;
+        } else {
             oldSource = log.useSource(newSource);
-            pos = ((JCTree) t).pos();
         }
 
         try {

langtools/src/share/classes/com/sun/tools/javac/comp/Attr.java

@@ -616,13 +616,13 @@ public class Attr extends JCTree.Visitor {
     /** Derived visitor method: attribute an expression tree with
      *  no constraints on the computed type.
      */
-    Type attribExpr(JCTree tree, Env<AttrContext> env) {
+    public Type attribExpr(JCTree tree, Env<AttrContext> env) {
         return attribTree(tree, env, unknownExprInfo);
     }
 
     /** Derived visitor method: attribute a type tree.
      */
-    Type attribType(JCTree tree, Env<AttrContext> env) {
+    public Type attribType(JCTree tree, Env<AttrContext> env) {
         Type result = attribType(tree, env, Type.noType);
         return result;
     }

langtools/src/share/classes/com/sun/tools/javac/comp/AttrContext.java

@@ -109,6 +109,7 @@ public class AttrContext {
                 pendingResolutionPhase.isVarargsRequired();
     }
 
+    @Override
     public String toString() {
         return "AttrContext[" + scope.toString() + "]";
     }

langtools/src/share/classes/com/sun/tools/javac/comp/Env.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2012, 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
@@ -122,6 +122,7 @@ public class Env<A> implements Iterable<Env<A>> {
         return env1;
     }
 
+    @Override
     public String toString() {
         return "Env[" + info + (outer == null ? "" : ",outer=" + outer) + "]";
     }

langtools/src/share/classes/com/sun/tools/javac/comp/Resolve.java

@@ -1731,7 +1731,7 @@ public class Resolve {
 
     /** Find an unqualified identifier which matches a specified kind set.
      *  @param env       The current environment.
-     *  @param name      The indentifier's name.
+     *  @param name      The identifier's name.
      *  @param kind      Indicates the possible symbol kinds
      *                   (a subset of VAL, TYP, PCK).
      */

langtools/src/share/classes/com/sun/tools/javac/parser/JavacParser.java

@@ -47,8 +47,8 @@ import static com.sun.tools.javac.parser.Tokens.TokenKind.EQ;
 import static com.sun.tools.javac.parser.Tokens.TokenKind.GT;
 import static com.sun.tools.javac.parser.Tokens.TokenKind.IMPORT;
 import static com.sun.tools.javac.parser.Tokens.TokenKind.LT;
-import static com.sun.tools.javac.util.ListBuffer.lb;
 import static com.sun.tools.javac.tree.JCTree.Tag.*;
+import static com.sun.tools.javac.util.ListBuffer.lb;
 
 /** The parser maps a token sequence into an abstract syntax
  *  tree. It operates by recursive descent, with code derived
@@ -128,7 +128,7 @@ public class JavacParser implements Parser {
         this.allowDefaultMethods = source.allowDefaultMethods() &&
                 fac.options.isSet("allowDefaultMethods"); //pre-lambda guard
         this.keepDocComments = keepDocComments;
-        docComments = newDocCommentTable(keepDocComments);
+        docComments = newDocCommentTable(keepDocComments, fac);
         this.keepLineMap = keepLineMap;
         this.errorTree = F.Erroneous();
         endPosTable = newEndPosTable(keepEndPositions);
@@ -140,8 +140,8 @@ public class JavacParser implements Parser {
                 : new EmptyEndPosTable();
     }
 
-    protected DocCommentTable newDocCommentTable(boolean keepDocComments) {
+    protected DocCommentTable newDocCommentTable(boolean keepDocComments, ParserFactory fac) {
-        return keepDocComments ? new SimpleDocCommentTable() : null;
+        return keepDocComments ? new LazyDocCommentTable(fac) : null;
     }
 
     /** Switch: Should generics be recognized?
@@ -232,7 +232,11 @@ public class JavacParser implements Parser {
 
     protected Token token;
 
-    protected void nextToken() {
+    public Token token() {
+        return token;
+    }
+
+    public void nextToken() {
         S.nextToken();
         token = S.token();
     }

langtools/src/share/classes/com/sun/tools/javac/parser/JavadocTokenizer.java

@@ -234,10 +234,12 @@ public class JavadocTokenizer extends JavaTokenizer {
             // If we find an exact match for pos, the other item in the pair
             // gives the source pos; otherwise, compute the source position
             // relative to the best match found in the array.
+            if (pos == Position.NOPOS)
+                return Position.NOPOS;
             if (pos < 0 || pos >= docComment.length())
-                throw new StringIndexOutOfBoundsException();
+                throw new StringIndexOutOfBoundsException(String.valueOf(pos));
             if (docPosns == null)
-                return -1;
+                return Position.NOPOS;
             int start = 0;
             int end = docPosns.length;
             while (start < end - 2) {

langtools/src/share/classes/com/sun/tools/javac/parser/LazyDocCommentTable.java

@@ -29,8 +29,10 @@ import java.util.HashMap;
 import java.util.Map;
 
 import com.sun.tools.javac.parser.Tokens.Comment;
+import com.sun.tools.javac.tree.DCTree.DCDocComment;
 import com.sun.tools.javac.tree.DocCommentTable;
 import com.sun.tools.javac.tree.JCTree;
+import com.sun.tools.javac.util.DiagnosticSource;
 
 
 /**
@@ -40,11 +42,24 @@ import com.sun.tools.javac.tree.JCTree;
  *  This code and its internal interfaces are subject to change or
  *  deletion without notice.</b>
  */
-public class SimpleDocCommentTable implements DocCommentTable {
+public class LazyDocCommentTable implements DocCommentTable {
-    Map<JCTree, Comment> table;
+    private static class Entry {
+        final Comment comment;
+        DCDocComment tree;
 
-    SimpleDocCommentTable() {
+        Entry(Comment c) {
-        table = new HashMap<JCTree, Comment>();
+            comment = c;
+        }
+    }
+
+    ParserFactory fac;
+    DiagnosticSource diagSource;
+    Map<JCTree, Entry> table;
+
+    LazyDocCommentTable(ParserFactory fac) {
+        this.fac = fac;
+        diagSource = fac.log.currentSource();
+        table = new HashMap<JCTree, Entry>();
     }
 
     public boolean hasComment(JCTree tree) {
@@ -52,7 +67,8 @@ public class SimpleDocCommentTable implements DocCommentTable {
     }
 
     public Comment getComment(JCTree tree) {
-        return table.get(tree);
+        Entry e = table.get(tree);
+        return (e == null) ? null : e.comment;
     }
 
     public String getCommentText(JCTree tree) {
@@ -60,8 +76,17 @@ public class SimpleDocCommentTable implements DocCommentTable {
         return (c == null) ? null : c.getText();
     }
 
+    public DCDocComment getCommentTree(JCTree tree) {
+        Entry e = table.get(tree);
+        if (e == null)
+            return null;
+        if (e.tree == null)
+            e.tree = new DocCommentParser(fac, diagSource, e.comment).parse();
+        return e.tree;
+    }
+
     public void putComment(JCTree tree, Comment c) {
-        table.put(tree, c);
+        table.put(tree, new Entry(c));
     }
 
 }

langtools/src/share/classes/com/sun/tools/javac/parser/ParserFactory.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2012, 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
@@ -25,7 +25,10 @@
 
 package com.sun.tools.javac.parser;
 
+import java.util.Locale;
+
 import com.sun.tools.javac.code.Source;
+import com.sun.tools.javac.tree.DocTreeMaker;
 import com.sun.tools.javac.tree.TreeMaker;
 import com.sun.tools.javac.util.Context;
 import com.sun.tools.javac.util.Log;
@@ -54,26 +57,30 @@ public class ParserFactory {
     }
 
     final TreeMaker F;
+    final DocTreeMaker docTreeMaker;
     final Log log;
     final Tokens tokens;
     final Source source;
     final Names names;
     final Options options;
     final ScannerFactory scannerFactory;
+    final Locale locale;
 
     protected ParserFactory(Context context) {
         super();
         context.put(parserFactoryKey, this);
         this.F = TreeMaker.instance(context);
+        this.docTreeMaker = DocTreeMaker.instance(context);
         this.log = Log.instance(context);
         this.names = Names.instance(context);
         this.tokens = Tokens.instance(context);
         this.source = Source.instance(context);
         this.options = Options.instance(context);
         this.scannerFactory = ScannerFactory.instance(context);
+        this.locale = context.get(Locale.class);
     }
 
-    public Parser newParser(CharSequence input, boolean keepDocComments, boolean keepEndPos, boolean keepLineMap) {
+    public JavacParser newParser(CharSequence input, boolean keepDocComments, boolean keepEndPos, boolean keepLineMap) {
         Lexer lexer = scannerFactory.newScanner(input, keepDocComments);
         return new JavacParser(this, lexer, keepDocComments, keepLineMap, keepEndPos);
     }

langtools/src/share/classes/com/sun/tools/javac/resources/compiler.properties

@@ -2336,4 +2336,52 @@ compiler.misc.where.description.typevar.1=\
 compiler.misc.where.description.intersection.1=\
     where {0} are intersection types:
 
+###
+# errors related to doc comments
+
+compiler.err.dc.bad.entity=\
+    bad HTML entity
+
+compiler.err.dc.bad.gt=\
+    bad use of ''>''
+
+compiler.err.dc.bad.inline.tag=\
+    incorrect use of inline tag
+
+compiler.err.dc.identifier.expected=\
+    identifier expected
+
+compiler.err.dc.malformed.html=\
+    malformed HTML
+
+compiler.err.dc.missing.semicolon=\
+    semicolon missing
+
+compiler.err.dc.no.tag.name=\
+    no tag name after '@'
+
+compiler.err.dc.gt.expected=\
+    ''>'' expected
+
+compiler.err.dc.ref.bad.parens=\
+    '')'' missing in reference
+
+compiler.err.dc.ref.syntax.error=\
+    syntax error in reference
+
+compiler.err.dc.ref.unexpected.input=\
+    unexpected text
+
+compiler.err.dc.unexpected.content=\
+    unexpected content
+
+compiler.err.dc.unterminated.inline.tag=\
+    unterminated inline tag
+
+compiler.err.dc.unterminated.signature=\
+    unterminated signature
+
+compiler.err.dc.unterminated.string=\
+    unterminated string
+
 

langtools/src/share/classes/com/sun/tools/javac/tree/DCTree.java

@@ -0,0 +1,848 @@
+/*
+ * Copyright (c) 2011, 2012, 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.tools.javac.tree;
+
+
+import javax.tools.Diagnostic;
+
+import com.sun.source.doctree.*;
+import com.sun.tools.javac.parser.Tokens.Comment;
+import com.sun.tools.javac.util.Assert;
+import com.sun.tools.javac.util.DiagnosticSource;
+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 javax.tools.JavaFileObject;
+
+/**
+ * <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 abstract class DCTree implements DocTree {
+
+    /**
+     * The position in the comment string.
+     * Use {@link #getSourcePosition getSourcePosition} to convert
+     * it to a position in the source file.
+     *
+     * TODO: why not simply translate all these values into
+     * source file positions? Is it useful to have string-offset
+     * positions as well?
+     */
+    public int pos;
+
+    public long getSourcePosition(DCDocComment dc) {
+        return dc.comment.getSourcePos(pos);
+    }
+
+    public JCDiagnostic.DiagnosticPosition pos(DCDocComment dc) {
+        return new SimpleDiagnosticPosition(dc.comment.getSourcePos(pos));
+    }
+
+    public static class DCDocComment extends DCTree implements DocCommentTree {
+        final Comment comment; // required for the implicit source pos table
+
+        public final List<DCTree> firstSentence;
+        public final List<DCTree> body;
+        public final List<DCTree> tags;
+
+        public DCDocComment(Comment comment,
+                List<DCTree> firstSentence, List<DCTree> body, List<DCTree> tags) {
+            this.comment = comment;
+            this.firstSentence = firstSentence;
+            this.body = body;
+            this.tags = tags;
+        }
+
+        public Kind getKind() {
+            return Kind.DOC_COMMENT;
+        }
+
+        public <R, D> R accept(DocTreeVisitor<R, D> v, D d) {
+            return v.visitDocComment(this, d);
+        }
+
+        public List<? extends DocTree> getFirstSentence() {
+            return firstSentence;
+        }
+
+        public List<? extends DocTree> getBody() {
+            return body;
+        }
+
+        public List<? extends DocTree> getBlockTags() {
+            return tags;
+        }
+
+    }
+
+    public static abstract class DCBlockTag extends DCTree implements InlineTagTree {
+        public String getTagName() {
+            return getKind().tagName;
+        }
+    }
+
+    public static abstract class DCInlineTag extends DCTree implements InlineTagTree {
+        public String getTagName() {
+            return getKind().tagName;
+        }
+    }
+
+    public static class DCAttribute extends DCTree implements AttributeTree {
+        public final Name name;
+        public final ValueKind vkind;
+        public final List<DCTree> value;
+
+        DCAttribute(Name name, ValueKind vkind, List<DCTree> value) {
+            Assert.check((vkind == ValueKind.EMPTY) ? (value == null) : (value != null));
+            this.name = name;
+            this.vkind = vkind;
+            this.value = value;
+        }
+
+        @Override
+        public Kind getKind() {
+            return Kind.ATTRIBUTE;
+        }
+
+        @Override
+        public <R, D> R accept(DocTreeVisitor<R, D> v, D d) {
+            return v.visitAttribute(this, d);
+        }
+
+        @Override
+        public Name getName() {
+            return name;
+        }
+
+        @Override
+        public ValueKind getValueKind() {
+            return vkind;
+        }
+
+        @Override
+        public List<DCTree> getValue() {
+            return value;
+        }
+    }
+
+    public static class DCAuthor extends DCInlineTag implements AuthorTree {
+        public final List<DCTree> name;
+
+        DCAuthor(List<DCTree> name) {
+            this.name = name;
+        }
+
+        @Override
+        public Kind getKind() {
+            return Kind.AUTHOR;
+        }
+
+        @Override
+        public <R, D> R accept(DocTreeVisitor<R, D> v, D d) {
+            return v.visitAuthor(this, d);
+        }
+
+        @Override
+        public List<? extends DocTree> getName() {
+            return name;
+        }
+    }
+
+    public static class DCComment extends DCTree implements CommentTree {
+        public final String body;
+
+        DCComment(String body) {
+            this.body = body;
+        }
+
+        @Override
+        public Kind getKind() {
+            return Kind.COMMENT;
+        }
+
+        @Override
+        public <R, D> R accept(DocTreeVisitor<R, D> v, D d) {
+            return v.visitComment(this, d);
+        }
+
+        @Override
+        public String getBody() {
+            return body;
+        }
+    }
+
+    public static class DCDeprecated extends DCBlockTag implements DeprecatedTree {
+        public final List<DCTree> body;
+
+        DCDeprecated(List<DCTree> body) {
+            this.body = body;
+        }
+
+        @Override
+        public Kind getKind() {
+            return Kind.DEPRECATED;
+        }
+
+        @Override
+        public <R, D> R accept(DocTreeVisitor<R, D> v, D d) {
+            return v.visitDeprecated(this, d);
+        }
+
+        @Override
+        public List<? extends DocTree> getBody() {
+            return body;
+        }
+    }
+
+    public static class DCDocRoot extends DCInlineTag implements DocRootTree {
+
+        @Override
+        public Kind getKind() {
+            return Kind.DOC_ROOT;
+        }
+
+        @Override
+        public <R, D> R accept(DocTreeVisitor<R, D> v, D d) {
+            return v.visitDocRoot(this, d);
+        }
+    }
+
+    public static class DCEndElement extends DCTree implements EndElementTree {
+        public final Name name;
+
+        DCEndElement(Name name) {
+            this.name = name;
+        }
+
+        @Override
+        public Kind getKind() {
+            return Kind.END_ELEMENT;
+        }
+
+        @Override
+        public <R, D> R accept(DocTreeVisitor<R, D> v, D d) {
+            return v.visitEndElement(this, d);
+        }
+
+        @Override
+        public Name getName() {
+            return name;
+        }
+    }
+
+    public static class DCEntity extends DCTree implements EntityTree {
+        public final Name name;
+
+        DCEntity(Name name) {
+            this.name = name;
+        }
+
+        @Override
+        public Kind getKind() {
+            return Kind.ENTITY;
+        }
+
+        @Override
+        public <R, D> R accept(DocTreeVisitor<R, D> v, D d) {
+            return v.visitEntity(this, d);
+        }
+
+        @Override
+        public Name getName() {
+            return name;
+        }
+    }
+
+    public static class DCErroneous extends DCTree implements ErroneousTree, JCDiagnostic.DiagnosticPosition {
+        public final String body;
+        public final JCDiagnostic diag;
+
+        DCErroneous(String body, JCDiagnostic.Factory diags, DiagnosticSource diagSource, String code, Object... args) {
+            this.body = body;
+            this.diag = diags.error(diagSource, this, code, args);
+        }
+
+        @Override
+        public Kind getKind() {
+            return Kind.ERRONEOUS;
+        }
+
+        @Override
+        public <R, D> R accept(DocTreeVisitor<R, D> v, D d) {
+            return v.visitErroneous(this, d);
+        }
+
+        @Override
+        public String getBody() {
+            return body;
+        }
+
+        @Override
+        public Diagnostic<JavaFileObject> getDiagnostic() {
+            return diag;
+        }
+
+        @Override
+        public JCTree getTree() {
+            return null;
+        }
+
+        @Override
+        public int getStartPosition() {
+            return pos;
+        }
+
+        @Override
+        public int getPreferredPosition() {
+            return pos + body.length() - 1;
+        }
+
+        @Override
+        public int getEndPosition(EndPosTable endPosTable) {
+            return pos + body.length();
+        }
+    }
+
+    public static class DCIdentifier extends DCTree implements IdentifierTree {
+        public final Name name;
+
+        DCIdentifier(Name name) {
+            this.name = name;
+        }
+
+        @Override
+        public Kind getKind() {
+            return Kind.IDENTIFIER;
+        }
+
+        @Override
+        public <R, D> R accept(DocTreeVisitor<R, D> v, D d) {
+            return v.visitIdentifier(this, d);
+        }
+
+        @Override
+        public Name getName() {
+            return name;
+        }
+    }
+
+    public static class DCInheritDoc extends DCInlineTag implements InheritDocTree {
+        @Override
+        public Kind getKind() {
+            return Kind.INHERIT_DOC;
+        }
+
+        @Override
+        public <R, D> R accept(DocTreeVisitor<R, D> v, D d) {
+            return v.visitInheritDoc(this, d);
+        }
+    }
+
+    public static class DCLink extends DCInlineTag implements LinkTree {
+        public final Kind kind;
+        public final DCReference ref;
+        public final List<DCTree> label;
+
+        DCLink(Kind kind, DCReference ref, List<DCTree> label) {
+            Assert.check(kind == Kind.LINK || kind == Kind.LINK_PLAIN);
+            this.kind = kind;
+            this.ref = ref;
+            this.label = label;
+        }
+
+        @Override
+        public Kind getKind() {
+            return kind;
+        }
+
+        @Override
+        public <R, D> R accept(DocTreeVisitor<R, D> v, D d) {
+            return v.visitLink(this, d);
+        }
+
+        @Override
+        public ReferenceTree getReference() {
+            return ref;
+        }
+
+        @Override
+        public List<? extends DocTree> getLabel() {
+            return label;
+        }
+    }
+
+    public static class DCLiteral extends DCInlineTag implements LiteralTree {
+        public final Kind kind;
+        public final DCText body;
+
+        DCLiteral(Kind kind, DCText body) {
+            Assert.check(kind == Kind.CODE || kind == Kind.LITERAL);
+            this.kind = kind;
+            this.body = body;
+        }
+
+        @Override
+        public Kind getKind() {
+            return kind;
+        }
+
+        @Override
+        public <R, D> R accept(DocTreeVisitor<R, D> v, D d) {
+            return v.visitLiteral(this, d);
+        }
+
+        @Override
+        public DCText getBody() {
+            return body;
+        }
+    }
+
+    public static class DCParam extends DCBlockTag implements ParamTree {
+        public final boolean isTypeParameter;
+        public final DCIdentifier name;
+        public final List<DCTree> description;
+
+        DCParam(boolean isTypeParameter, DCIdentifier name, List<DCTree> description) {
+            this.isTypeParameter = isTypeParameter;
+            this.name = name;
+            this.description = description;
+        }
+
+        @Override
+        public Kind getKind() {
+            return Kind.PARAM;
+        }
+
+        @Override
+        public <R, D> R accept(DocTreeVisitor<R, D> v, D d) {
+            return v.visitParam(this, d);
+        }
+
+        @Override
+        public boolean isTypeParameter() {
+            return isTypeParameter;
+        }
+
+        @Override
+        public IdentifierTree getName() {
+            return name;
+        }
+
+        @Override
+        public List<? extends DocTree> getDescription() {
+            return description;
+        }
+    }
+
+    public static class DCReference extends DCTree implements ReferenceTree {
+        public final String signature;
+
+        // The following are not directly exposed through ReferenceTree
+        // use DocTrees.getElement(TreePath,ReferenceTree)
+        public final JCTree qualifierExpression;
+        public final Name memberName;
+        public final List<JCTree> paramTypes;
+
+
+        DCReference(String signature, JCTree qualExpr, Name member, List<JCTree> paramTypes) {
+            this.signature = signature;
+            qualifierExpression = qualExpr;
+            memberName = member;
+            this.paramTypes = paramTypes;
+        }
+
+        @Override
+        public Kind getKind() {
+            return Kind.REFERENCE;
+        }
+
+        @Override
+        public <R, D> R accept(DocTreeVisitor<R, D> v, D d) {
+            return v.visitReference(this, d);
+        }
+
+        @Override
+        public String getSignature() {
+            return signature;
+        }
+    }
+
+    public static class DCReturn extends DCBlockTag implements ReturnTree {
+        public final List<DCTree> description;
+
+        DCReturn(List<DCTree> description) {
+            this.description = description;
+        }
+
+        @Override
+        public Kind getKind() {
+            return Kind.RETURN;
+        }
+
+        @Override
+        public <R, D> R accept(DocTreeVisitor<R, D> v, D d) {
+            return v.visitReturn(this, d);
+        }
+
+        @Override
+        public List<? extends DocTree> getDescription() {
+            return description;
+        }
+    }
+
+    public static class DCSee extends DCBlockTag implements SeeTree {
+        public final List<DCTree> reference;
+
+        DCSee(List<DCTree> reference) {
+            this.reference = reference;
+        }
+
+        @Override
+        public Kind getKind() {
+            return Kind.SEE;
+        }
+
+        @Override
+        public <R, D> R accept(DocTreeVisitor<R, D> v, D d) {
+            return v.visitSee(this, d);
+        }
+
+        @Override
+        public List<? extends DocTree> getReference() {
+            return reference;
+        }
+    }
+
+    public static class DCSerial extends DCBlockTag implements SerialTree {
+        public final List<DCTree> description;
+
+        DCSerial(List<DCTree> description) {
+            this.description = description;
+        }
+
+        @Override
+        public Kind getKind() {
+            return Kind.SERIAL;
+        }
+
+        @Override
+        public <R, D> R accept(DocTreeVisitor<R, D> v, D d) {
+            return v.visitSerial(this, d);
+        }
+
+        @Override
+        public List<? extends DocTree> getDescription() {
+            return description;
+        }
+    }
+
+    public static class DCSerialData extends DCBlockTag implements SerialDataTree {
+        public final List<DCTree> description;
+
+        DCSerialData(List<DCTree> description) {
+            this.description = description;
+        }
+
+        @Override
+        public Kind getKind() {
+            return Kind.SERIAL_DATA;
+        }
+
+        @Override
+        public <R, D> R accept(DocTreeVisitor<R, D> v, D d) {
+            return v.visitSerialData(this, d);
+        }
+
+        @Override
+        public List<? extends DocTree> getDescription() {
+            return description;
+        }
+    }
+
+    public static class DCSerialField extends DCBlockTag implements SerialFieldTree {
+        public final DCIdentifier name;
+        public final DCReference type;
+        public final List<DCTree> description;
+
+        DCSerialField(DCIdentifier name, DCReference type, List<DCTree> description) {
+            this.description = description;
+            this.name = name;
+            this.type = type;
+        }
+
+        @Override
+        public Kind getKind() {
+            return Kind.SERIAL_FIELD;
+        }
+
+        @Override
+        public <R, D> R accept(DocTreeVisitor<R, D> v, D d) {
+            return v.visitSerialField(this, d);
+        }
+
+        @Override
+        public List<? extends DocTree> getDescription() {
+            return description;
+        }
+
+        @Override
+        public IdentifierTree getName() {
+            return name;
+        }
+
+        @Override
+        public ReferenceTree getType() {
+            return type;
+        }
+    }
+
+    public static class DCSince extends DCInlineTag implements SinceTree {
+        public final List<DCTree> body;
+
+        DCSince(List<DCTree> body) {
+            this.body = body;
+        }
+
+        @Override
+        public Kind getKind() {
+            return Kind.SINCE;
+        }
+
+        @Override
+        public <R, D> R accept(DocTreeVisitor<R, D> v, D d) {
+            return v.visitSince(this, d);
+        }
+
+        @Override
+        public List<? extends DocTree> getBody() {
+            return body;
+        }
+    }
+
+    public static class DCStartElement extends DCTree implements StartElementTree {
+        public final Name name;
+        public final List<DCTree> attrs;
+        public final boolean selfClosing;
+
+        DCStartElement(Name name, List<DCTree> attrs, boolean selfClosing) {
+            this.name = name;
+            this.attrs = attrs;
+            this.selfClosing = selfClosing;
+        }
+
+        @Override
+        public Kind getKind() {
+            return Kind.START_ELEMENT;
+        }
+
+        @Override
+        public <R, D> R accept(DocTreeVisitor<R, D> v, D d) {
+            return v.visitStartElement(this, d);
+        }
+
+        @Override
+        public Name getName() {
+            return name;
+        }
+
+        @Override
+        public List<? extends DocTree> getAttributes() {
+            return attrs;
+        }
+
+        @Override
+        public boolean isSelfClosing() {
+            return selfClosing;
+        }
+    }
+
+    public static class DCText extends DCTree implements TextTree {
+        public final String text;
+
+        DCText(String text) {
+            this.text = text;
+        }
+
+        @Override
+        public Kind getKind() {
+            return Kind.TEXT;
+        }
+
+        @Override
+        public <R, D> R accept(DocTreeVisitor<R, D> v, D d) {
+            return v.visitText(this, d);
+        }
+
+        @Override
+        public String getBody() {
+            return text;
+        }
+    }
+
+    public static class DCThrows extends DCBlockTag implements ThrowsTree {
+        public final Kind kind;
+        public final DCReference name;
+        public final List<DCTree> description;
+
+        DCThrows(Kind kind, DCReference name, List<DCTree> description) {
+            Assert.check(kind == Kind.EXCEPTION || kind == Kind.THROWS);
+            this.kind = kind;
+            this.name = name;
+            this.description = description;
+        }
+
+        @Override
+        public Kind getKind() {
+            return kind;
+        }
+
+        @Override
+        public <R, D> R accept(DocTreeVisitor<R, D> v, D d) {
+            return v.visitThrows(this, d);
+        }
+
+        @Override
+        public ReferenceTree getExceptionName() {
+            return name;
+        }
+
+        @Override
+        public List<? extends DocTree> getDescription() {
+            return description;
+        }
+    }
+
+    public static class DCUnknownBlockTag extends DCBlockTag implements UnknownBlockTagTree {
+        public final Name name;
+        public final List<DCTree> content;
+
+        DCUnknownBlockTag(Name name, List<DCTree> content) {
+            this.name = name;
+            this.content = content;
+        }
+
+        @Override
+        public Kind getKind() {
+            return Kind.UNKNOWN_BLOCK_TAG;
+        }
+
+        @Override
+        public <R, D> R accept(DocTreeVisitor<R, D> v, D d) {
+            return v.visitUnknownBlockTag(this, d);
+        }
+
+        @Override
+        public String getTagName() {
+            return name.toString();
+        }
+
+        @Override
+        public List<? extends DocTree> getContent() {
+            return content;
+        }
+    }
+
+    public static class DCUnknownInlineTag extends DCInlineTag implements UnknownInlineTagTree {
+        public final Name name;
+        public final List<DCTree> content;
+
+        DCUnknownInlineTag(Name name, List<DCTree> content) {
+            this.name = name;
+            this.content = content;
+        }
+
+        @Override
+        public Kind getKind() {
+            return Kind.UNKNOWN_INLINE_TAG;
+        }
+
+        @Override
+        public <R, D> R accept(DocTreeVisitor<R, D> v, D d) {
+            return v.visitUnknownInlineTag(this, d);
+        }
+
+        @Override
+        public String getTagName() {
+            return name.toString();
+        }
+
+        @Override
+        public List<? extends DocTree> getContent() {
+            return content;
+        }
+    }
+
+    public static class DCValue extends DCInlineTag implements ValueTree {
+        public final DCReference ref;
+
+        DCValue(DCReference ref) {
+            this.ref = ref;
+        }
+
+        @Override
+        public Kind getKind() {
+            return Kind.VALUE;
+        }
+
+        @Override
+        public <R, D> R accept(DocTreeVisitor<R, D> v, D d) {
+            return v.visitValue(this, d);
+        }
+
+        @Override
+        public ReferenceTree getReference() {
+            return ref;
+        }
+    }
+
+    public static class DCVersion extends DCBlockTag implements VersionTree {
+        public final List<DCTree> body;
+
+        DCVersion(List<DCTree> body) {
+            this.body = body;
+        }
+
+        @Override
+        public Kind getKind() {
+            return Kind.VERSION;
+        }
+
+        @Override
+        public <R, D> R accept(DocTreeVisitor<R, D> v, D d) {
+            return v.visitVersion(this, d);
+        }
+
+        @Override
+        public List<? extends DocTree> getBody() {
+            return body;
+        }
+    }
+
+}

langtools/src/share/classes/com/sun/tools/javac/tree/DocCommentTable.java

@@ -24,7 +24,9 @@
  */
 package com.sun.tools.javac.tree;
 
+import com.sun.source.doctree.ErroneousTree;
 import com.sun.tools.javac.parser.Tokens.Comment;
+import com.sun.tools.javac.tree.DCTree.DCDocComment;
 
 /**
  * A table giving the doc comment, if any, for any tree node.
@@ -50,6 +52,13 @@ public interface DocCommentTable {
      */
     public String getCommentText(JCTree tree);
 
+    /**
+     * Get the parsed form of the doc comment as a DocTree. If any errors
+     * are detected during parsing, they will be reported via
+     * {@link ErroneousTree ErroneousTree} nodes within the resulting tree.
+     */
+    public DCDocComment getCommentTree(JCTree tree);
+
     /**
      * Set the Comment to be associated with a tree node.
      */

langtools/src/share/classes/com/sun/tools/javac/tree/DocPretty.java

@@ -0,0 +1,520 @@
+/*
+ * Copyright (c) 1999, 2012, 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.tools.javac.tree;
+
+import java.io.Writer;
+
+import com.sun.source.doctree.*;
+import com.sun.source.doctree.AttributeTree.ValueKind;
+import com.sun.tools.javac.util.Convert;
+import java.io.IOException;
+import java.util.List;
+
+/**
+ * Prints out a doc comment tree.
+ *
+ *  <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 DocPretty implements DocTreeVisitor<Void,Void> {
+
+    /**
+     * The output stream on which trees are printed.
+     */
+    final Writer out;
+
+    /**
+     * The left margin.
+     */
+    int lmargin = 0;
+
+    public DocPretty(Writer out) {
+        this.out = out;
+    }
+
+    /** Visitor method: print expression tree.
+     */
+    public void print(DocTree tree) throws IOException {
+        try {
+            if (tree == null)
+                print("/*missing*/");
+            else {
+                tree.accept(this, null);
+            }
+        } catch (UncheckedIOException ex) {
+            throw new IOException(ex.getMessage(), ex);
+        }
+    }
+
+    /**
+     * Print string, replacing all non-ascii character with unicode escapes.
+     */
+    protected void print(Object s) throws IOException {
+        out.write(Convert.escapeUnicode(s.toString()));
+    }
+
+    /**
+     * Print list.
+     */
+    protected void print(List<? extends DocTree> list) throws IOException {
+        for (DocTree t: list) {
+            print(t);
+        }
+    }
+
+    /**
+     * Print list., with separators
+     */
+    protected void print(List<? extends DocTree> list, String sep) throws IOException {
+        if (list.isEmpty())
+            return;
+        boolean first = true;
+        for (DocTree t: list) {
+            if (!first)
+                print(sep);
+            print(t);
+            first = false;
+        }
+    }
+
+    /** Print new line.
+     */
+    protected void println() throws IOException {
+        out.write(lineSep);
+    }
+
+    protected void printTagName(DocTree node) throws IOException {
+        out.write("@");
+        out.write(node.getKind().tagName);
+    }
+
+    final String lineSep = System.getProperty("line.separator");
+
+    /**************************************************************************
+     * Traversal methods
+     *************************************************************************/
+
+    /** Exception to propagate IOException through visitXXX methods */
+    private static class UncheckedIOException extends Error {
+        static final long serialVersionUID = -4032692679158424751L;
+        UncheckedIOException(IOException e) {
+            super(e.getMessage(), e);
+        }
+    }
+
+
+    public Void visitAttribute(AttributeTree node, Void p) {
+        try {
+            print(node.getName());
+            String quote;
+            switch (node.getValueKind()) {
+                case EMPTY:
+                    quote = null;
+                    break;
+                case UNQUOTED:
+                    quote = "";
+                    break;
+                case SINGLE:
+                    quote = "'";
+                    break;
+                case DOUBLE:
+                    quote = "\"";
+                    break;
+                default:
+                    throw new AssertionError();
+            }
+            if (quote != null) {
+                print("=" + quote);
+                print(node.getValue());
+                print(quote);
+            }
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+        return null;
+    }
+
+    public Void visitAuthor(AuthorTree node, Void p) {
+        try {
+            printTagName(node);
+            print(" ");
+            print(node.getName());
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+        return null;
+    }
+
+    public Void visitComment(CommentTree node, Void p) {
+        try {
+            print(node.getBody());
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+        return null;
+    }
+
+    public Void visitDeprecated(DeprecatedTree node, Void p) {
+        try {
+            printTagName(node);
+            if (!node.getBody().isEmpty()) {
+                print(" ");
+                print(node.getBody());
+            }
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+        return null;
+    }
+
+    public Void visitDocComment(DocCommentTree node, Void p) {
+        try {
+            List<? extends DocTree> fs = node.getFirstSentence();
+            List<? extends DocTree> b = node.getBody();
+            List<? extends DocTree> t = node.getBlockTags();
+            print(fs);
+            if (!fs.isEmpty() && !b.isEmpty())
+                print(" ");
+            print(b);
+            if ((!fs.isEmpty() || !b.isEmpty()) && !t.isEmpty())
+                print("\n");
+            print(t, "\n");
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+        return null;
+    }
+
+    public Void visitDocRoot(DocRootTree node, Void p) {
+        try {
+            print("{");
+            printTagName(node);
+            print("}");
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+        return null;
+    }
+
+    public Void visitEndElement(EndElementTree node, Void p) {
+        try {
+            print("</");
+            print(node.getName());
+            print(">");
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+        return null;
+    }
+
+    public Void visitEntity(EntityTree node, Void p) {
+        try {
+            print("&");
+            print(node.getName());
+            print(";");
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+        return null;
+    }
+
+    public Void visitErroneous(ErroneousTree node, Void p) {
+        try {
+            print(node.getBody());
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+        return null;
+    }
+
+    public Void visitIdentifier(IdentifierTree node, Void p) {
+        try {
+            print(node.getName());
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+        return null;
+    }
+
+    public Void visitInheritDoc(InheritDocTree node, Void p) {
+        try {
+            print("{");
+            printTagName(node);
+            print("}");
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+        return null;
+    }
+
+    public Void visitLink(LinkTree node, Void p) {
+        try {
+            print("{");
+            printTagName(node);
+            print(" ");
+            print(node.getReference());
+            if (!node.getLabel().isEmpty()) {
+                print(" ");
+                print(node.getLabel());
+            }
+            print("}");
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+        return null;
+    }
+
+    public Void visitLiteral(LiteralTree node, Void p) {
+        try {
+            print("{");
+            printTagName(node);
+            print(" ");
+            print(node.getBody());
+            print("}");
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+        return null;
+    }
+
+    public Void visitParam(ParamTree node, Void p) {
+        try {
+            printTagName(node);
+            print(" ");
+            if (node.isTypeParameter()) print("<");
+            print(node.getName());
+            if (node.isTypeParameter()) print(">");
+            if (!node.getDescription().isEmpty()) {
+                print(" ");
+                print(node.getDescription());
+            }
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+        return null;
+    }
+
+    public Void visitReference(ReferenceTree node, Void p) {
+        try {
+            print(node.getSignature());
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+        return null;
+    }
+
+    public Void visitReturn(ReturnTree node, Void p) {
+        try {
+            printTagName(node);
+            print(" ");
+            print(node.getDescription());
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+        return null;
+    }
+
+    public Void visitSee(SeeTree node, Void p) {
+        try {
+            printTagName(node);
+            boolean first = true;
+            boolean needSep = true;
+            for (DocTree t: node.getReference()) {
+                if (needSep) print(" ");
+                needSep = (first && (t instanceof ReferenceTree));
+                first = false;
+                print(t);
+            }
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+        return null;
+    }
+
+    public Void visitSerial(SerialTree node, Void p) {
+        try {
+            printTagName(node);
+            if (!node.getDescription().isEmpty()) {
+                print(" ");
+                print(node.getDescription());
+            }
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+        return null;
+    }
+
+    public Void visitSerialData(SerialDataTree node, Void p) {
+        try {
+            printTagName(node);
+            if (!node.getDescription().isEmpty()) {
+                print(" ");
+                print(node.getDescription());
+            }
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+        return null;
+    }
+
+    public Void visitSerialField(SerialFieldTree node, Void p) {
+        try {
+            printTagName(node);
+            print(" ");
+            print(node.getName());
+            print(" ");
+            print(node.getType());
+            if (!node.getDescription().isEmpty()) {
+                print(" ");
+                print(node.getDescription());
+            }
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+        return null;
+    }
+
+    public Void visitSince(SinceTree node, Void p) {
+        try {
+            printTagName(node);
+            print(" ");
+            print(node.getBody());
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+        return null;
+    }
+
+    public Void visitStartElement(StartElementTree node, Void p) {
+        try {
+            print("<");
+            print(node.getName());
+            List<? extends DocTree> attrs = node.getAttributes();
+            if (!attrs.isEmpty()) {
+                print(" ");
+                print(attrs);
+                DocTree last = node.getAttributes().get(attrs.size() - 1);
+                if (node.isSelfClosing() && last instanceof AttributeTree
+                        && ((AttributeTree) last).getValueKind() == ValueKind.UNQUOTED)
+                    print(" ");
+            }
+            if (node.isSelfClosing())
+                print("/");
+            print(">");
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+        return null;
+    }
+
+    public Void visitText(TextTree node, Void p) {
+        try {
+            print(node.getBody());
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+        return null;
+    }
+
+    public Void visitThrows(ThrowsTree node, Void p) {
+        try {
+            printTagName(node);
+            print(" ");
+            print(node.getExceptionName());
+            if (!node.getDescription().isEmpty()) {
+                print(" ");
+                print(node.getDescription());
+            }
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+        return null;
+    }
+
+    public Void visitUnknownBlockTag(UnknownBlockTagTree node, Void p) {
+        try {
+            print("@");
+            print(node.getTagName());
+            print(" ");
+            print(node.getContent());
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+        return null;
+    }
+
+    public Void visitUnknownInlineTag(UnknownInlineTagTree node, Void p) {
+        try {
+            print("{");
+            print("@");
+            print(node.getTagName());
+            print(" ");
+            print(node.getContent());
+            print("}");
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+        return null;
+    }
+
+    public Void visitValue(ValueTree node, Void p) {
+        try {
+            print("{");
+            printTagName(node);
+            if (node.getReference() != null) {
+                print(" ");
+                print(node.getReference());
+            }
+            print("}");
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+        return null;
+    }
+
+    public Void visitVersion(VersionTree node, Void p) {
+        try {
+            printTagName(node);
+            print(" ");
+            print(node.getBody());
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+        return null;
+    }
+
+    public Void visitOther(DocTree node, Void p) {
+        try {
+            print("(UNKNOWN: " + node + ")");
+            println();
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+        return null;
+    }
+}

langtools/src/share/classes/com/sun/tools/javac/tree/DocTreeMaker.java

@@ -0,0 +1,277 @@
+/*
+ * Copyright (c) 2011, 2012, 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.tools.javac.tree;
+
+import com.sun.source.doctree.AttributeTree.ValueKind;
+import com.sun.source.doctree.DocTree.Kind;
+
+import com.sun.tools.javac.parser.Tokens.Comment;
+import com.sun.tools.javac.tree.DCTree.*;
+import com.sun.tools.javac.util.Context;
+import com.sun.tools.javac.util.DiagnosticSource;
+import com.sun.tools.javac.util.JCDiagnostic;
+import com.sun.tools.javac.util.JCDiagnostic.DiagnosticPosition;
+import com.sun.tools.javac.util.List;
+import com.sun.tools.javac.util.Name;
+import com.sun.tools.javac.util.Position;
+
+/**
+ *
+ *  <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 DocTreeMaker {
+
+    /** The context key for the tree factory. */
+    protected static final Context.Key<DocTreeMaker> treeMakerKey =
+        new Context.Key<DocTreeMaker>();
+
+    /** Get the TreeMaker instance. */
+    public static DocTreeMaker instance(Context context) {
+        DocTreeMaker instance = context.get(treeMakerKey);
+        if (instance == null)
+            instance = new DocTreeMaker(context);
+        return instance;
+    }
+
+    /** The position at which subsequent trees will be created.
+     */
+    public int pos = Position.NOPOS;
+
+    /** Access to diag factory for ErroneousTrees. */
+    private final JCDiagnostic.Factory diags;
+
+    /** Create a tree maker with NOPOS as initial position.
+     */
+    protected DocTreeMaker(Context context) {
+        context.put(treeMakerKey, this);
+        diags = JCDiagnostic.Factory.instance(context);
+        this.pos = Position.NOPOS;
+    }
+
+    /** Reassign current position.
+     */
+    public DocTreeMaker at(int pos) {
+        this.pos = pos;
+        return this;
+    }
+
+    /** Reassign current position.
+     */
+    public DocTreeMaker at(DiagnosticPosition pos) {
+        this.pos = (pos == null ? Position.NOPOS : pos.getStartPosition());
+        return this;
+    }
+
+    public DCAttribute Attribute(Name name, ValueKind vkind, List<DCTree> value) {
+        DCAttribute tree = new DCAttribute(name, vkind, value);
+        tree.pos = pos;
+        return tree;
+    }
+
+    public DCAuthor Author(List<DCTree> name) {
+        DCAuthor tree = new DCAuthor(name);
+        tree.pos = pos;
+        return tree;
+    }
+
+    public DCLiteral Code(DCText text) {
+        DCLiteral tree = new DCLiteral(Kind.CODE, text);
+        tree.pos = pos;
+        return tree;
+    }
+
+    public DCComment Comment(String text) {
+        DCComment tree = new DCComment(text);
+        tree.pos = pos;
+        return tree;
+    }
+
+    public DCDeprecated Deprecated(List<DCTree> text) {
+        DCDeprecated tree = new DCDeprecated(text);
+        tree.pos = pos;
+        return tree;
+    }
+
+    public DCDocComment DocComment(Comment comment, List<DCTree> firstSentence, List<DCTree> body, List<DCTree> tags) {
+        DCDocComment tree = new DCDocComment(comment, firstSentence, body, tags);
+        tree.pos = pos;
+        return tree;
+    }
+
+    public DCDocRoot DocRoot() {
+        DCDocRoot tree = new DCDocRoot();
+        tree.pos = pos;
+        return tree;
+    }
+
+    public DCEndElement EndElement(Name name) {
+        DCEndElement tree = new DCEndElement(name);
+        tree.pos = pos;
+        return tree;
+    }
+
+    public DCEntity Entity(Name name) {
+        DCEntity tree = new DCEntity(name);
+        tree.pos = pos;
+        return tree;
+    }
+
+    public DCErroneous Erroneous(String text, DiagnosticSource diagSource, String code, Object... args) {
+        DCErroneous tree = new DCErroneous(text, diags, diagSource, code, args);
+        tree.pos = pos;
+        return tree;
+    }
+
+    public DCThrows Exception(DCReference name, List<DCTree> description) {
+        DCThrows tree = new DCThrows(Kind.EXCEPTION, name, description);
+        tree.pos = pos;
+        return tree;
+    }
+
+    public DCIdentifier Identifier(Name name) {
+        DCIdentifier tree = new DCIdentifier(name);
+        tree.pos = pos;
+        return tree;
+    }
+
+    public DCInheritDoc InheritDoc() {
+        DCInheritDoc tree = new DCInheritDoc();
+        tree.pos = pos;
+        return tree;
+    }
+
+    public DCLink Link(DCReference ref, List<DCTree> label) {
+        DCLink tree = new DCLink(Kind.LINK, ref, label);
+        tree.pos = pos;
+        return tree;
+    }
+
+    public DCLink LinkPlain(DCReference ref, List<DCTree> label) {
+        DCLink tree = new DCLink(Kind.LINK_PLAIN, ref, label);
+        tree.pos = pos;
+        return tree;
+    }
+
+    public DCLiteral Literal(DCText text) {
+        DCLiteral tree = new DCLiteral(Kind.LITERAL, text);
+        tree.pos = pos;
+        return tree;
+    }
+
+    public DCParam Param(boolean isTypeParameter, DCIdentifier name, List<DCTree> description) {
+        DCParam tree = new DCParam(isTypeParameter, name, description);
+        tree.pos = pos;
+        return tree;
+    }
+
+    public DCReference Reference(String signature,
+            JCTree qualExpr, Name member, List<JCTree> paramTypes) {
+        DCReference tree = new DCReference(signature, qualExpr, member, paramTypes);
+        tree.pos = pos;
+        return tree;
+    }
+
+    public DCReturn Return(List<DCTree> description) {
+        DCReturn tree = new DCReturn(description);
+        tree.pos = pos;
+        return tree;
+    }
+
+    public DCSee See(List<DCTree> reference) {
+        DCSee tree = new DCSee(reference);
+        tree.pos = pos;
+        return tree;
+    }
+
+    public DCSerial Serial(List<DCTree> description) {
+        DCSerial tree = new DCSerial(description);
+        tree.pos = pos;
+        return tree;
+    }
+
+    public DCSerialData SerialData(List<DCTree> description) {
+        DCSerialData tree = new DCSerialData(description);
+        tree.pos = pos;
+        return tree;
+    }
+
+    public DCSerialField SerialField(DCIdentifier name, DCReference type, List<DCTree> description) {
+        DCSerialField tree = new DCSerialField(name, type, description);
+        tree.pos = pos;
+        return tree;
+    }
+
+    public DCSince Since(List<DCTree> text) {
+        DCSince tree = new DCSince(text);
+        tree.pos = pos;
+        return tree;
+    }
+
+    public DCStartElement StartElement(Name name, List<DCTree> attrs, boolean selfClosing) {
+        DCStartElement tree = new DCStartElement(name, attrs, selfClosing);
+        tree.pos = pos;
+        return tree;
+    }
+
+    public DCText Text(String text) {
+        DCText tree = new DCText(text);
+        tree.pos = pos;
+        return tree;
+    }
+
+    public DCThrows Throws(DCReference name, List<DCTree> description) {
+        DCThrows tree = new DCThrows(Kind.THROWS, name, description);
+        tree.pos = pos;
+        return tree;
+    }
+
+    public DCUnknownBlockTag UnknownBlockTag(Name name, List<DCTree> content) {
+        DCUnknownBlockTag tree = new DCUnknownBlockTag(name, content);
+        tree.pos = pos;
+        return tree;
+    }
+
+    public DCUnknownInlineTag UnknownInlineTag(Name name, List<DCTree> content) {
+        DCUnknownInlineTag tree = new DCUnknownInlineTag(name, content);
+        tree.pos = pos;
+        return tree;
+    }
+
+    public DCValue Value(DCReference ref) {
+        DCValue tree = new DCValue(ref);
+        tree.pos = pos;
+        return tree;
+    }
+
+    public DCVersion Version(List<DCTree> text) {
+        DCVersion tree = new DCVersion(text);
+        tree.pos = pos;
+        return tree;
+    }
+}

langtools/src/share/classes/com/sun/tools/javadoc/DocEnv.java

@@ -102,6 +102,7 @@ public class DocEnv {
     Check chk;
     Types types;
     JavaFileManager fileManager;
+    Context context;
 
     /** Allow documenting from class files? */
     boolean docClasses = false;
@@ -122,6 +123,7 @@ public class DocEnv {
      */
     protected DocEnv(Context context) {
         context.put(docEnvKey, this);
+        this.context = context;
 
         messager = Messager.instance0(context);
         syms = Symtab.instance(context);

langtools/src/share/classes/com/sun/tools/javadoc/SeeTagImpl.java

@@ -25,7 +25,14 @@
 
 package com.sun.tools.javadoc;
 
+import java.io.File;
+import java.util.Locale;
+
 import com.sun.javadoc.*;
+import com.sun.tools.javac.code.Kinds;
+import com.sun.tools.javac.code.Printer;
+import com.sun.tools.javac.code.Symbol;
+import com.sun.tools.javac.code.Type.CapturedType;
 import com.sun.tools.javac.util.*;
 
 /**
@@ -75,9 +82,63 @@ class SeeTagImpl extends TagImpl implements SeeTag, LayoutCharacters {
                 container = (ClassDocImpl)holder;
             }
             findReferenced(container);
+            if (showRef) showRef();
         }
     }
 
+    private static final boolean showRef = false;
+
+    private void showRef() {
+        Symbol sym;
+        if (referencedMember != null) {
+            if (referencedMember instanceof MethodDocImpl)
+                sym = ((MethodDocImpl) referencedMember).sym;
+            else if (referencedMember instanceof FieldDocImpl)
+                sym = ((FieldDocImpl) referencedMember).sym;
+            else
+                sym = ((ConstructorDocImpl) referencedMember).sym;
+        } else if (referencedClass != null) {
+            sym = ((ClassDocImpl) referencedClass).tsym;
+        } else if (referencedPackage != null) {
+            sym = ((PackageDocImpl) referencedPackage).sym;
+        } else
+            return;
+
+        final JavacMessages messages = JavacMessages.instance(docenv().context);
+        Locale locale = Locale.getDefault();
+        Printer printer = new Printer() {
+            int count;
+            @Override
+            protected String localize(Locale locale, String key, Object... args) {
+                return messages.getLocalizedString(locale, key, args);
+            }
+            @Override
+            protected String capturedVarId(CapturedType t, Locale locale) {
+                return "CAP#" + (++count);
+            }
+        };
+
+        String s = text.replaceAll("\\s+", " ");  // normalize white space
+        int sp = s.indexOf(" ");
+        int lparen = s.indexOf("(");
+        int rparen = s.indexOf(")");
+        String seetext = (sp == -1) ? s
+                : (lparen == -1 || sp < lparen) ? s.substring(0, sp)
+                : s.substring(0, rparen + 1);
+
+        File file = new File(holder.position().file().getAbsoluteFile().toURI().normalize());
+
+        StringBuilder sb = new StringBuilder();
+        sb.append("+++ ").append(file).append(": ")
+                .append(name()).append(" ").append(seetext).append(": ");
+        sb.append(sym.getKind()).append(" ");
+        if (sym.kind == Kinds.MTH || sym.kind == Kinds.VAR)
+            sb.append(printer.visit(sym.owner, locale)).append(".");
+        sb.append(printer.visit(sym, locale));
+
+        System.err.println(sb);
+    }
+
     /**
      * get the class name part of @see, For instance,
      * if the comment is @see String#startsWith(java.lang.String) .

langtools/test/tools/javac/diags/CheckExamples.java

@@ -25,9 +25,10 @@
  * @test
  * @bug 6968063 7127924
  * @summary provide examples of code that generate diagnostics
- * @build Example CheckExamples
+ * @build Example CheckExamples DocCommentProcessor
  * @run main/othervm CheckExamples
  */
+
 /*
  *      See CR 7127924 for info on why othervm is used.
  */

langtools/test/tools/javac/diags/DocCommentProcessor.java

@@ -0,0 +1,114 @@
+/*
+ * Copyright (c) 2012, 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.
+ */
+
+import java.util.*;
+
+import javax.annotation.processing.*;
+import javax.lang.model.*;
+import javax.lang.model.element.*;
+
+import com.sun.source.doctree.DocCommentTree;
+import com.sun.source.doctree.ErroneousTree;
+import com.sun.source.tree.ClassTree;
+import com.sun.source.tree.MethodTree;
+import com.sun.source.tree.VariableTree;
+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 com.sun.source.util.TreeScanner;
+import com.sun.tools.javac.tree.DocPretty;
+import java.io.PrintWriter;
+import javax.tools.Diagnostic;
+
+/**
+ * Standard annotation processor for use by examples to
+ * scan DocCommentTree nodes looking for ErroneousTree,
+ * on which to call {@code getMessage}.
+ */
+@SupportedAnnotationTypes("*")
+public class DocCommentProcessor extends AbstractProcessor {
+    @Override
+    public SourceVersion getSupportedSourceVersion() {
+        return SourceVersion.latest();
+    }
+
+    @Override
+    public void init(ProcessingEnvironment pEnv) {
+        super.init(pEnv);
+        trees = DocTrees.instance(pEnv);
+        messager = pEnv.getMessager();
+    }
+
+    @Override
+    public boolean process(Set<? extends TypeElement> annos, RoundEnvironment rEnv) {
+        for (Element e : rEnv.getRootElements()) {
+            new DocCommentScanner().scan(e);
+        }
+        return true;
+    }
+
+    class DocCommentScanner extends TreePathScanner<Void,Void> {
+        public void scan(Element e) {
+            scan(trees.getPath(e), null);
+        }
+
+        @Override
+        public Void visitClass(ClassTree tree, Void ignore) {
+            check();
+            return super.visitClass(tree, ignore);
+        }
+
+        @Override
+        public Void visitMethod(MethodTree tree, Void ignore) {
+            check();
+            return super.visitMethod(tree, ignore);
+        }
+
+        @Override
+        public Void visitVariable(VariableTree tree, Void ignore) {
+            check();
+            return super.visitVariable(tree, ignore);
+        }
+
+        private void check() {
+            DocCommentTree dc = trees.getDocCommentTree(getCurrentPath());
+            if (dc == null)
+                return;
+
+            DocTreeScanner<Void, Void> s = new DocTreeScanner<Void, Void>() {
+                @Override
+                public Void visitErroneous(ErroneousTree tree, Void ignore) {
+                    messager.printMessage(Diagnostic.Kind.NOTE, tree.getDiagnostic().getMessage(null));
+                    return null;
+                }
+            };
+
+            s.scan(dc, null);
+        }
+
+    }
+
+    private DocTrees trees;
+    private Messager messager;
+}

langtools/test/tools/javac/diags/Example.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2012, 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
@@ -209,6 +209,13 @@ class Example implements Comparable<Example> {
             opts.add("-classpath"); // avoid using -processorpath for now
             opts.add(classesDir.getPath());
             createAnnotationServicesFile(classesDir, procFiles);
+        } else if (options != null) {
+            int i = options.indexOf("-processor");
+            // check for built-in anno-processor(s)
+            if (i != -1 && options.get(i + 1).equals("DocCommentProcessor")) {
+                opts.add("-classpath");
+                opts.add(System.getProperty("test.classes"));
+            }
         }
 
         if (srcPathDir != null) {

langtools/test/tools/javac/diags/RunExamples.java

@@ -25,7 +25,7 @@
  * @test
  * @bug 6968063 7127924
  * @summary provide examples of code that generate diagnostics
- * @build ArgTypeCompilerFactory Example HTMLWriter RunExamples
+ * @build ArgTypeCompilerFactory Example HTMLWriter RunExamples DocCommentProcessor
  * @run main/othervm RunExamples
  */
 /*

langtools/test/tools/javac/diags/examples.not-yet.txt

@@ -3,6 +3,7 @@ compiler.err.already.defined.this.unit                  # seems to be masked by
 compiler.err.annotation.value.not.allowable.type        # cannot happen: precluded by complete type-specific tests
 compiler.err.cant.read.file                             # (apt.JavaCompiler?)
 compiler.err.cant.select.static.class.from.param.type
+compiler.err.dc.unterminated.string                     # cannot happen
 compiler.err.illegal.char.for.encoding
 compiler.err.invalid.containedby.annotation             # should not happen
 compiler.err.invalid.containedby.annotation.invalid.value # "can't" happen
@@ -105,3 +106,4 @@ compiler.warn.unchecked.cast.to.type                    # DEAD, replaced by comp
 compiler.warn.unexpected.archive.file                   # Paths: zip file with unknown extn
 compiler.warn.unknown.enum.constant                     # in bad class file
 compiler.warn.unknown.enum.constant.reason              # in bad class file
+

langtools/test/tools/javac/diags/examples/BadEntity.java

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) 2012, 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.
+ */
+
+// key: compiler.err.dc.bad.entity
+// key: compiler.note.note
+// key: compiler.note.proc.messager
+// run: backdoor
+// options: -processor DocCommentProcessor -proc:only
+
+/** & */
+class BadEntity { }
+

langtools/test/tools/javac/diags/examples/BadGreaterThan.java

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) 2012, 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.
+ */
+
+// key: compiler.err.dc.bad.gt
+// key: compiler.note.note
+// key: compiler.note.proc.messager
+// run: backdoor
+// options: -processor DocCommentProcessor -proc:only
+
+/** > */
+class BadGreaterThan { }
+

langtools/test/tools/javac/diags/examples/BadInlineTag.java

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) 2012, 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.
+ */
+
+// key: compiler.err.dc.bad.inline.tag
+// key: compiler.note.note
+// key: compiler.note.proc.messager
+// run: backdoor
+// options: -processor DocCommentProcessor -proc:only
+
+/** @inheritDoc */
+class BadInlineTag { }
+

langtools/test/tools/javac/diags/examples/GreaterThanExpected.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright (c) 2012, 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.
+ */
+
+// key: compiler.err.dc.gt.expected
+// key: compiler.note.note
+// key: compiler.note.proc.messager
+// run: backdoor
+// options: -processor DocCommentProcessor -proc:only
+
+class GreaterThanExpected {
+    /** @param <T */
+    <T> void m(T t) { }
+}
+

langtools/test/tools/javac/diags/examples/MalformedHTML.java

@@ -0,0 +1,31 @@
+/*
+ * Copyright (c) 2012, 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.
+ */
+
+// key: compiler.err.dc.malformed.html
+// key: compiler.note.note
+// key: compiler.note.proc.messager
+// run: backdoor
+// options: -processor DocCommentProcessor -proc:only
+
+/** <b */
+class MalformedHTML { }

langtools/test/tools/javac/diags/examples/MissingSemicolon.java

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) 2012, 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.
+ */
+
+// key: compiler.err.dc.missing.semicolon
+// key: compiler.note.note
+// key: compiler.note.proc.messager
+// run: backdoor
+// options: -processor DocCommentProcessor -proc:only
+
+/** &lt */
+class MissingSemicolon { }
+

langtools/test/tools/javac/diags/examples/NoTagName.java

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) 2012, 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.
+ */
+
+// key: compiler.err.dc.no.tag.name
+// key: compiler.note.note
+// key: compiler.note.proc.messager
+// run: backdoor
+// options: -processor DocCommentProcessor -proc:only
+
+/** @ */
+class NoTagName { }
+

langtools/test/tools/javac/diags/examples/RefBadParens.java

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) 2012, 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.
+ */
+
+// key: compiler.err.dc.ref.bad.parens
+// key: compiler.note.note
+// key: compiler.note.proc.messager
+// run: backdoor
+// options: -processor DocCommentProcessor -proc:only
+
+/** @see #m((int)) */
+class RefBadParens { }
+

langtools/test/tools/javac/diags/examples/RefIdentifierExpected.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright (c) 2012, 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.
+ */
+
+// key: compiler.err.dc.identifier.expected
+// key: compiler.note.note
+// key: compiler.note.proc.messager
+// run: backdoor
+// options: -processor DocCommentProcessor -proc:only
+
+class IdentifierExpected2 {
+    /** @param 123 */
+    void m() { }
+}
+

langtools/test/tools/javac/diags/examples/RefSyntaxError.java

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) 2012, 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.
+ */
+
+// key: compiler.err.dc.ref.syntax.error
+// key: compiler.note.note
+// key: compiler.note.proc.messager
+// run: backdoor
+// options: -processor DocCommentProcessor -proc:only
+
+/** @see #m(int [) */
+class RefSyntaxError { }
+

langtools/test/tools/javac/diags/examples/RefUnexpectedInput.java

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) 2012, 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.
+ */
+
+// key: compiler.err.dc.ref.unexpected.input
+// key: compiler.note.note
+// key: compiler.note.proc.messager
+// run: backdoor
+// options: -processor DocCommentProcessor -proc:only
+
+/** @see String#isEmpty% */
+class UnexpectedInput { }
+

langtools/test/tools/javac/diags/examples/UnexpectedContent.java

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) 2012, 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.
+ */
+
+// key: compiler.err.dc.unexpected.content
+// key: compiler.note.note
+// key: compiler.note.proc.messager
+// run: backdoor
+// options: -processor DocCommentProcessor -proc:only
+
+/** {@docRoot a} */
+class UnterminatedSignature { }
+

langtools/test/tools/javac/diags/examples/UnterminatedInlineTag.java

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) 2012, 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.
+ */
+
+// key: compiler.err.dc.unterminated.inline.tag
+// key: compiler.note.note
+// key: compiler.note.proc.messager
+// run: backdoor
+// options: -processor DocCommentProcessor -proc:only
+
+/** {@code */
+class UnterminatedInlineTag { }
+

langtools/test/tools/javac/diags/examples/UnterminatedSignature.java

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) 2012, 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.
+ */
+
+// key: compiler.err.dc.unterminated.signature
+// key: compiler.note.note
+// key: compiler.note.proc.messager
+// run: backdoor
+// options: -processor DocCommentProcessor -proc:only
+
+/** @see String#equals( */
+class UnterminatedSignature { }
+

langtools/test/tools/javac/doctree/AttrTest.java

@@ -0,0 +1,281 @@
+/*
+ * Copyright (c) 2012, 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 7021614
+ * @summary extend com.sun.source API to support parsing javadoc comments
+ * @build DocCommentTester
+ * @run main DocCommentTester AttrTest.java
+ */
+
+class AttrTest {
+    /**
+     * <a name=unquoted>foo</a>
+     */
+    void unquoted_attr() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 3
+    StartElement[START_ELEMENT, pos:1
+      name:a
+      attributes: 1
+        Attribute[ATTRIBUTE, pos:4
+          name: name
+          vkind: UNQUOTED
+          value: 1
+            Text[TEXT, pos:9, unquoted]
+        ]
+    ]
+    Text[TEXT, pos:18, foo]
+    EndElement[END_ELEMENT, pos:21, a]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * <a name="double_quoted">foo</a>
+     */
+    void double_quoted_attr() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 3
+    StartElement[START_ELEMENT, pos:1
+      name:a
+      attributes: 1
+        Attribute[ATTRIBUTE, pos:4
+          name: name
+          vkind: DOUBLE
+          value: 1
+            Text[TEXT, pos:10, double_quoted]
+        ]
+    ]
+    Text[TEXT, pos:25, foo]
+    EndElement[END_ELEMENT, pos:28, a]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * <a name='single_quoted'>foo</a>
+     */
+    void single_quoted_attr() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 3
+    StartElement[START_ELEMENT, pos:1
+      name:a
+      attributes: 1
+        Attribute[ATTRIBUTE, pos:4
+          name: name
+          vkind: SINGLE
+          value: 1
+            Text[TEXT, pos:10, single_quoted]
+        ]
+    ]
+    Text[TEXT, pos:25, foo]
+    EndElement[END_ELEMENT, pos:28, a]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * <hr size="3">
+     */
+    void numeric_attr() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 1
+    StartElement[START_ELEMENT, pos:1
+      name:hr
+      attributes: 1
+        Attribute[ATTRIBUTE, pos:5
+          name: size
+          vkind: DOUBLE
+          value: 1
+            Text[TEXT, pos:11, 3]
+        ]
+    ]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * <a href="{@docRoot}/index.html">
+     */
+    void docRoot_attr() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 1
+    StartElement[START_ELEMENT, pos:1
+      name:a
+      attributes: 1
+        Attribute[ATTRIBUTE, pos:4
+          name: href
+          vkind: DOUBLE
+          value: 2
+            DocRoot[DOC_ROOT, pos:10]
+            Text[TEXT, pos:20, /index.html]
+        ]
+    ]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * <a name="abc&quot;def">
+     */
+    void entity_attr() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 1
+    StartElement[START_ELEMENT, pos:1
+      name:a
+      attributes: 1
+        Attribute[ATTRIBUTE, pos:4
+          name: name
+          vkind: DOUBLE
+          value: 3
+            Text[TEXT, pos:10, abc]
+            Entity[ENTITY, pos:13, quot]
+            Text[TEXT, pos:19, def]
+        ]
+    ]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * <hr noshade>
+     */
+    void no_value_attr() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 1
+    StartElement[START_ELEMENT, pos:1
+      name:hr
+      attributes: 1
+        Attribute[ATTRIBUTE, pos:5
+          name: noshade
+          vkind: EMPTY
+          value: null
+        ]
+    ]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * abc <hr size='3'/>
+     */
+    void self_closing_attr_1() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 2
+    Text[TEXT, pos:1, abc_]
+    StartElement[START_ELEMENT, pos:5
+      name:hr
+      attributes: 1
+        Attribute[ATTRIBUTE, pos:9
+          name: size
+          vkind: SINGLE
+          value: 1
+            Text[TEXT, pos:15, 3]
+        ]
+    ]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * abc <hr size=3 />
+     */
+    void self_closing_attr_2() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 2
+    Text[TEXT, pos:1, abc_]
+    StartElement[START_ELEMENT, pos:5
+      name:hr
+      attributes: 1
+        Attribute[ATTRIBUTE, pos:9
+          name: size
+          vkind: UNQUOTED
+          value: 1
+            Text[TEXT, pos:14, 3]
+        ]
+    ]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * abc <hr size="3
+     */
+    void unterminated_attr_eoi() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 3
+    Text[TEXT, pos:1, abc_]
+    Erroneous[ERRONEOUS, pos:5
+      code: compiler.err.dc.malformed.html
+      body: <
+    ]
+    Text[TEXT, pos:6, hr_size="3]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * abc <hr size="3
+     * @author jjg
+     */
+    void unterminated_attr_block() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 3
+    Text[TEXT, pos:1, abc_]
+    Erroneous[ERRONEOUS, pos:5
+      code: compiler.err.dc.malformed.html
+      body: <
+    ]
+    Text[TEXT, pos:6, hr_size="3]
+  body: empty
+  block tags: 1
+    Author[AUTHOR, pos:18
+      name: 1
+        Text[TEXT, pos:26, jjg]
+    ]
+]
+*/
+}

langtools/test/tools/javac/doctree/AuthorTest.java

@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) 2012, 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 7021614
+ * @summary extend com.sun.source API to support parsing javadoc comments
+ * @build DocCommentTester
+ * @run main DocCommentTester AuthorTest.java
+ */
+
+class AuthorTest {
+    /** abc @author jjg & others */
+    void standard() { }
+/*
+DocComment[DOC_COMMENT, pos:0
+  firstSentence: 3
+    Text[TEXT, pos:0, abc_@author_jjg_]
+    Entity[ENTITY, pos:16, amp]
+    Text[TEXT, pos:21, _others]
+  body: empty
+  block tags: empty
+]
+*/
+
+}

langtools/test/tools/javac/doctree/BadTest.java

@@ -0,0 +1,52 @@
+/*
+ * Copyright (c) 2012, 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 7021614
+ * @summary extend com.sun.source API to support parsing javadoc comments
+ * @build DocCommentTester
+ * @run main DocCommentTester Bad.java
+ */
+
+class BadTest {
+
+    /**
+     * abc {@value java.awt.Color#RED junk}
+     */
+    int trailing_junk() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 3
+    Text[TEXT, pos:1, abc_]
+    Erroneous[ERRONEOUS, pos:5
+      code: compiler.err.dc.unexpected.content
+      body: {@value_java.awt.Color#RED_j
+    ]
+    Text[TEXT, pos:33, unk}]
+  body: empty
+  block tags: empty
+]
+*/
+
+}

langtools/test/tools/javac/doctree/CodeTest.java

@@ -0,0 +1,133 @@
+/*
+ * Copyright (c) 2012, 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 7021614
+ * @summary extend com.sun.source API to support parsing javadoc comments
+ * @build DocCommentTester
+ * @run main DocCommentTester CodeTest.java
+ */
+
+class CodeTest {
+    /** {@code if (a < b) { }} */
+    void minimal() { }
+/*
+DocComment[DOC_COMMENT, pos:0
+  firstSentence: 1
+    Literal[CODE, pos:0, if_(a_<_b)_{_}]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /** [{@code if (a < b) { }}] */
+    void in_brackets() { }
+/*
+DocComment[DOC_COMMENT, pos:0
+  firstSentence: 3
+    Text[TEXT, pos:0, []
+    Literal[CODE, pos:1, if_(a_<_b)_{_}]
+    Text[TEXT, pos:23, ]]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /** [ {@code if (a < b) { }} ] */
+    void in_brackets_with_whitespace() { }
+/*
+DocComment[DOC_COMMENT, pos:0
+  firstSentence: 3
+    Text[TEXT, pos:0, [_]
+    Literal[CODE, pos:2, if_(a_<_b)_{_}]
+    Text[TEXT, pos:24, _]]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * {@code {@code nested} }
+     */
+    void nested() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 1
+    Literal[CODE, pos:1, {@code_nested}_]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * {@code if (a < b) {
+     *        }
+     * }
+     */
+    void embedded_newline() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 1
+    Literal[CODE, pos:1, if_(a_<_b)_{|________}|_]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /** {@code if (a < b) { } */
+    void unterminated_1() { }
+/*
+DocComment[DOC_COMMENT, pos:0
+  firstSentence: 1
+    Erroneous[ERRONEOUS, pos:0
+      code: compiler.err.dc.unterminated.inline.tag
+      body: {@code_if_(a_<_b)_{_}
+    ]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * {@code if (a < b) { }
+     * @author jjg */
+    void unterminated_2() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 1
+    Erroneous[ERRONEOUS, pos:1
+      code: compiler.err.dc.unterminated.inline.tag
+      body: {@code_if_(a_<_b)_{_}
+    ]
+  body: empty
+  block tags: 1
+    Author[AUTHOR, pos:24
+      name: 1
+        Text[TEXT, pos:32, jjg]
+    ]
+]
+*/
+
+}
+

langtools/test/tools/javac/doctree/DeprecatedTest.java

@@ -0,0 +1,64 @@
+/*
+ * Copyright (c) 2012, 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 7021614
+ * @summary extend com.sun.source API to support parsing javadoc comments
+ * @build DocCommentTester
+ * @run main DocCommentTester DeprecatedTest.java
+ */
+
+class DeprecatedTest {
+    /**
+     * @deprecated
+     */
+    void deprecated() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: empty
+  body: empty
+  block tags: 1
+    Deprecated[DEPRECATED, pos:1
+      body: empty
+    ]
+]
+*/
+
+    /**
+     * @deprecated text
+     */
+    void deprecated_text() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: empty
+  body: empty
+  block tags: 1
+    Deprecated[DEPRECATED, pos:1
+      body: 1
+        Text[TEXT, pos:13, text]
+    ]
+]
+*/
+
+}

langtools/test/tools/javac/doctree/DocCommentTester.java

@@ -0,0 +1,778 @@
+/*
+ * Copyright (c) 2012, 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.
+ */
+
+import java.io.File;
+import java.io.FileWriter;
+import java.io.IOException;
+import java.io.PrintWriter;
+import java.io.StringWriter;
+import java.io.Writer;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+import javax.lang.model.element.Name;
+import javax.tools.JavaFileObject;
+import javax.tools.StandardJavaFileManager;
+
+import com.sun.source.doctree.*;
+import com.sun.source.tree.ClassTree;
+import com.sun.source.tree.CompilationUnitTree;
+import com.sun.source.tree.MethodTree;
+import com.sun.source.tree.Tree;
+import com.sun.source.tree.VariableTree;
+import com.sun.source.util.DocTreeScanner;
+import com.sun.source.util.DocTrees;
+import com.sun.source.util.JavacTask;
+import com.sun.source.util.TreePath;
+import com.sun.source.util.TreePathScanner;
+import com.sun.tools.javac.api.JavacTool;
+import com.sun.tools.javac.tree.DCTree;
+import com.sun.tools.javac.tree.DCTree.DCDocComment;
+import com.sun.tools.javac.tree.DCTree.DCErroneous;
+import com.sun.tools.javac.tree.DocPretty;
+
+public class DocCommentTester {
+
+    public static void main(String... args) throws Exception {
+        new DocCommentTester().run(args);
+    }
+
+    public void run(String... args) throws Exception {
+        String testSrc = System.getProperty("test.src");
+
+        List<File> files = new ArrayList<File>();
+        for (String arg: args)
+            files.add(new File(testSrc, arg));
+
+        JavacTool javac = JavacTool.create();
+        StandardJavaFileManager fm = javac.getStandardFileManager(null, null, null);
+
+        Iterable<? extends JavaFileObject> fos = fm.getJavaFileObjectsFromFiles(files);
+
+        JavacTask t = javac.getTask(null, fm, null, null, null, fos);
+        final DocTrees trees = DocTrees.instance(t);
+
+        final Checker[] checkers = {
+            new ASTChecker(this, trees),
+            new PosChecker(this, trees),
+            new PrettyChecker(this, trees)
+        };
+
+        DeclScanner d = new DeclScanner() {
+            @Override
+            public Void visitCompilationUnit(CompilationUnitTree tree, Void ignore) {
+                for (Checker c: checkers)
+                    c.visitCompilationUnit(tree);
+                return super.visitCompilationUnit(tree, ignore);
+            }
+
+            @Override
+            void visitDecl(Tree tree, Name name) {
+                TreePath path = getCurrentPath();
+                String dc = trees.getDocComment(path);
+                if (dc != null) {
+                    for (Checker c : checkers) {
+                        try {
+                            System.err.println(path.getLeaf().getKind()
+                                    + " " + name
+                                    + " " + c.getClass().getSimpleName());
+
+                            c.check(path, name);
+
+                            System.err.println();
+                        } catch (Exception e) {
+                            error("Exception " + e);
+                            e.printStackTrace(System.err);
+                        }
+                    }
+                }
+            }
+        };
+
+        Iterable<? extends CompilationUnitTree> units = t.parse();
+        for (CompilationUnitTree unit: units) {
+            d.scan(unit, null);
+        }
+
+        if (errors > 0)
+            throw new Exception(errors + " errors occurred");
+    }
+
+    static abstract class DeclScanner extends TreePathScanner<Void, Void> {
+        abstract void visitDecl(Tree tree, Name name);
+
+        @Override
+        public Void visitClass(ClassTree tree, Void ignore) {
+            super.visitClass(tree, ignore);
+            visitDecl(tree, tree.getSimpleName());
+            return null;
+        }
+
+        @Override
+        public Void visitMethod(MethodTree tree, Void ignore) {
+            super.visitMethod(tree, ignore);
+            visitDecl(tree, tree.getName());
+            return null;
+        }
+
+        @Override
+        public Void visitVariable(VariableTree tree, Void ignore) {
+            super.visitVariable(tree, ignore);
+            visitDecl(tree, tree.getName());
+            return null;
+        }
+    }
+
+    /**
+     * Base class for checkers to check the doc comment on a declaration
+     * (when present.)
+     */
+    abstract class Checker {
+        final DocTrees trees;
+
+        Checker(DocTrees trees) {
+            this.trees = trees;
+        }
+
+        void visitCompilationUnit(CompilationUnitTree tree) { }
+
+        abstract void check(TreePath tree, Name name) throws Exception;
+
+        void error(String msg) {
+            DocCommentTester.this.error(msg);
+        }
+    }
+
+    void error(String msg) {
+        System.err.println("Error: " + msg);
+        errors++;
+    }
+
+    int errors;
+
+    /**
+     * Verify the structure of the DocTree AST by comparing it against golden text.
+     */
+    static class ASTChecker extends Checker {
+        Printer printer = new Printer();
+        String source;
+
+        ASTChecker(DocCommentTester test, DocTrees t) {
+            test.super(t);
+        }
+
+        @Override
+        void visitCompilationUnit(CompilationUnitTree tree) {
+            try {
+                source = tree.getSourceFile().getCharContent(true).toString();
+            } catch (IOException e) {
+                source = "";
+            }
+        }
+
+        void check(TreePath path, Name name) {
+            StringWriter out = new StringWriter();
+            DocCommentTree dc = trees.getDocCommentTree(path);
+            printer.print(dc, out);
+            out.flush();
+            String found = out.toString();
+
+            // Look for the first block comment after the first occurrence of name
+            int start = source.indexOf("\n/*\n", findName(source, name));
+            int end = source.indexOf("\n*/\n", start);
+            String expect = source.substring(start + 4, end + 1);
+            if (!found.equals(expect)) {
+                System.err.println("Expect:\n" + expect);
+                System.err.println("Found:\n" + found);
+                error("AST mismatch for " + name);
+            }
+        }
+
+        /**
+         * This main program is to set up the golden comments used by this
+         * checker.
+         * Usage:
+         *     java DocCommentTester$ASTChecker -o dir file...
+         * The given files are written to the output directory with their
+         * golden comments updated. The intent is that the files should
+         * then be compared with the originals, e.g. with meld, and if the
+         * changes are approved, the new files can be used to replace the old.
+         */
+        public static void main(String... args) throws Exception {
+            List<File> files = new ArrayList<File>();
+            File o = null;
+            for (int i = 0; i < args.length; i++) {
+                String arg = args[i];
+                if (arg.equals("-o"))
+                    o = new File(args[++i]);
+                else if (arg.startsWith("-"))
+                    throw new IllegalArgumentException(arg);
+                else {
+                    files.add(new File(arg));
+                }
+            }
+
+            if (o == null)
+                throw new IllegalArgumentException("no output dir specified");
+            final File outDir = o;
+
+            JavacTool javac = JavacTool.create();
+            StandardJavaFileManager fm = javac.getStandardFileManager(null, null, null);
+            Iterable<? extends JavaFileObject> fos = fm.getJavaFileObjectsFromFiles(files);
+
+            JavacTask t = javac.getTask(null, fm, null, null, null, fos);
+            final DocTrees trees = DocTrees.instance(t);
+
+            DeclScanner d = new DeclScanner() {
+                Printer p = new Printer();
+                String source;
+
+                @Override
+                public Void visitCompilationUnit(CompilationUnitTree tree, Void ignore) {
+                    System.err.println("processing " + tree.getSourceFile().getName());
+                    try {
+                        source = tree.getSourceFile().getCharContent(true).toString();
+                    } catch (IOException e) {
+                        source = "";
+                    }
+
+                    // remove existing gold by removing all block comments after the first '{'.
+                    int start = source.indexOf("{");
+                    while ((start = source.indexOf("\n/*\n", start)) != -1) {
+                        int end = source.indexOf("\n*/\n");
+                        source = source.substring(0, start + 1) + source.substring(end + 4);
+                    }
+
+                    // process decls in compilation unit
+                    super.visitCompilationUnit(tree, ignore);
+
+                    // write the modified source
+                    File f = new File(tree.getSourceFile().getName());
+                    File outFile = new File(outDir, f.getName());
+                    try {
+                        FileWriter out = new FileWriter(outFile);
+                        try {
+                            out.write(source);
+                        } finally {
+                            out.close();
+                        }
+                    } catch (IOException e) {
+                        System.err.println("Can't write " + tree.getSourceFile().getName()
+                                + " to " + outFile + ": " + e);
+                    }
+                    return null;
+                }
+
+                @Override
+                void visitDecl(Tree tree, Name name) {
+                    DocTree dc = trees.getDocCommentTree(getCurrentPath());
+                    if (dc != null) {
+                        StringWriter out = new StringWriter();
+                        p.print(dc, out);
+                        String found = out.toString();
+
+                        // Look for the empty line after the first occurrence of name
+                        int pos = source.indexOf("\n\n", findName(source, name));
+
+                        // Insert the golden comment
+                        source = source.substring(0, pos)
+                                + "\n/*\n"
+                                + found
+                                + "*/"
+                                + source.substring(pos);
+                    }
+                }
+
+            };
+
+            Iterable<? extends CompilationUnitTree> units = t.parse();
+            for (CompilationUnitTree unit: units) {
+                d.scan(unit, null);
+            }
+        }
+
+        static int findName(String source, Name name) {
+            Pattern p = Pattern.compile("\\s" + name + "[(;]");
+            Matcher m = p.matcher(source);
+            if (!m.find())
+                throw new Error("cannot find " + name);
+            return m.start();
+        }
+
+        static class Printer implements DocTreeVisitor<Void, Void> {
+            PrintWriter out;
+
+            void print(DocTree tree, Writer out) {
+                this.out = (out instanceof PrintWriter)
+                        ? (PrintWriter) out : new PrintWriter(out);
+                tree.accept(this, null);
+                this.out.flush();
+            }
+
+            public Void visitAttribute(AttributeTree node, Void p) {
+                header(node);
+                indent(+1);
+                print("name", node.getName().toString());
+                print("vkind", node.getValueKind().toString());
+                print("value", node.getValue());
+                indent(-1);
+                indent();
+                out.println("]");
+                return null;
+            }
+
+            public Void visitAuthor(AuthorTree node, Void p) {
+                header(node);
+                indent(+1);
+                print("name", node.getName());
+                indent(-1);
+                indent();
+                out.println("]");
+                return null;
+            }
+
+            public Void visitComment(CommentTree node, Void p) {
+                header(node, compress(node.getBody()));
+                return null;
+            }
+
+            public Void visitDeprecated(DeprecatedTree node, Void p) {
+                header(node);
+                indent(+1);
+                print("body", node.getBody());
+                indent(-1);
+                indent();
+                out.println("]");
+                return null;
+            }
+
+            public Void visitDocComment(DocCommentTree node, Void p) {
+                header(node);
+                indent(+1);
+                print("firstSentence", node.getFirstSentence());
+                print("body", node.getBody());
+                print("block tags", node.getBlockTags());
+                indent(-1);
+                indent();
+                out.println("]");
+                return null;
+            }
+
+            public Void visitDocRoot(DocRootTree node, Void p) {
+                header(node, "");
+                return null;
+            }
+
+            public Void visitEndElement(EndElementTree node, Void p) {
+                header(node, node.getName().toString());
+                return null;
+            }
+
+            public Void visitEntity(EntityTree node, Void p) {
+                header(node, node.getName().toString());
+                return null;
+            }
+
+            public Void visitErroneous(ErroneousTree node, Void p) {
+                header(node);
+                indent(+1);
+                print("code", ((DCErroneous) node).diag.getCode());
+                print("body", compress(node.getBody()));
+                indent(-1);
+                indent();
+                out.println("]");
+                return null;
+            }
+
+            public Void visitIdentifier(IdentifierTree node, Void p) {
+                header(node, compress(node.getName().toString()));
+                return null;
+            }
+
+            public Void visitInheritDoc(InheritDocTree node, Void p) {
+                header(node, "");
+                return null;
+            }
+
+            public Void visitLink(LinkTree node, Void p) {
+                header(node);
+                indent(+1);
+                print("reference", node.getReference());
+                print("body", node.getLabel());
+                indent(-1);
+                indent();
+                out.println("]");
+                return null;
+            }
+
+            public Void visitLiteral(LiteralTree node, Void p) {
+                header(node, compress(node.getBody().getBody()));
+                return null;
+            }
+
+            public Void visitParam(ParamTree node, Void p) {
+                header(node);
+                indent(+1);
+                print("name", node.getName());
+                print("description", node.getDescription());
+                indent(-1);
+                indent();
+                out.println("]");
+                return null;
+            }
+
+            public Void visitReference(ReferenceTree node, Void p) {
+                header(node, compress(node.getSignature()));
+                return null;
+            }
+
+            public Void visitReturn(ReturnTree node, Void p) {
+                header(node);
+                indent(+1);
+                print("description", node.getDescription());
+                indent(-1);
+                indent();
+                out.println("]");
+                return null;
+            }
+
+            public Void visitSee(SeeTree node, Void p) {
+                header(node);
+                indent(+1);
+                print("reference", node.getReference());
+                indent(-1);
+                indent();
+                out.println("]");
+                return null;
+            }
+
+            public Void visitSerial(SerialTree node, Void p) {
+                header(node);
+                indent(+1);
+                print("description", node.getDescription());
+                indent(-1);
+                indent();
+                out.println("]");
+                return null;
+            }
+
+            public Void visitSerialData(SerialDataTree node, Void p) {
+                header(node);
+                indent(+1);
+                print("description", node.getDescription());
+                indent(-1);
+                indent();
+                out.println("]");
+                return null;
+            }
+
+            public Void visitSerialField(SerialFieldTree node, Void p) {
+                header(node);
+                indent(+1);
+                print("name", node.getName());
+                print("type", node.getType());
+                print("description", node.getDescription());
+                indent(-1);
+                indent();
+                out.println("]");
+                return null;
+            }
+
+            public Void visitSince(SinceTree node, Void p) {
+                header(node);
+                indent(+1);
+                print("body", node.getBody());
+                indent(-1);
+                indent();
+                out.println("]");
+                return null;
+            }
+
+            public Void visitStartElement(StartElementTree node, Void p) {
+                header(node);
+                indent(+1);
+                indent();
+                out.println("name:" + node.getName());
+                print("attributes", node.getAttributes());
+                indent(-1);
+                indent();
+                out.println("]");
+                return null;
+            }
+
+            public Void visitText(TextTree node, Void p) {
+                header(node, compress(node.getBody()));
+                return null;
+            }
+
+            public Void visitThrows(ThrowsTree node, Void p) {
+                header(node);
+                indent(+1);
+                print("exceptionName", node.getExceptionName());
+                print("description", node.getDescription());
+                indent(-1);
+                indent();
+                out.println("]");
+                return null;
+            }
+
+            public Void visitUnknownBlockTag(UnknownBlockTagTree node, Void p) {
+                header(node);
+                indent(+1);
+                indent();
+                out.println("tag:" + node.getTagName());
+                print("content", node.getContent());
+                indent(-1);
+                indent();
+                out.println("]");
+                return null;
+            }
+
+            public Void visitUnknownInlineTag(UnknownInlineTagTree node, Void p) {
+                header(node);
+                indent(+1);
+                indent();
+                out.println("tag:" + node.getTagName());
+                print("content", node.getContent());
+                indent(-1);
+                indent();
+                out.println("]");
+                return null;
+            }
+
+            public Void visitValue(ValueTree node, Void p) {
+                header(node);
+                indent(+1);
+                print("reference", node.getReference());
+                indent(-1);
+                indent();
+                out.println("]");
+                return null;
+            }
+
+            public Void visitVersion(VersionTree node, Void p) {
+                header(node);
+                indent(+1);
+                print("body", node.getBody());
+                indent(-1);
+                indent();
+                out.println("]");
+                return null;
+            }
+
+            public Void visitOther(DocTree node, Void p) {
+                throw new UnsupportedOperationException("Not supported yet.");
+            }
+
+            void header(DocTree node) {
+                indent();
+                out.println(simpleClassName(node) + "[" + node.getKind() + ", pos:" + ((DCTree) node).pos);
+            }
+
+            void header(DocTree node, String rest) {
+                indent();
+                out.println(simpleClassName(node) + "[" + node.getKind() + ", pos:" + ((DCTree) node).pos
+                        + (rest.isEmpty() ? "" : ", " + rest)
+                        + "]");
+            }
+
+            String simpleClassName(DocTree node) {
+                return node.getClass().getSimpleName().replaceAll("DC(.*)", "$1");
+            }
+
+            void print(String name, DocTree item) {
+                indent();
+                if (item == null)
+                    out.println(name + ": null");
+                else {
+                    out.println(name + ":");
+                    indent(+1);
+                    item.accept(this, null);
+                    indent(-1);
+                }
+            }
+
+            void print(String name, String s) {
+                indent();
+                out.println(name + ": " + s);
+            }
+
+            void print(String name, List<? extends DocTree> list) {
+                indent();
+                if (list == null)
+                    out.println(name + ": null");
+                else if (list.isEmpty())
+                    out.println(name + ": empty");
+                else {
+                    out.println(name + ": " + list.size());
+                    indent(+1);
+                    for (DocTree tree: list) {
+                        tree.accept(this, null);
+                    }
+                    indent(-1);
+                }
+            }
+
+            int indent = 0;
+
+            void indent() {
+                for (int i = 0; i < indent; i++) {
+                    out.print("  ");
+                }
+            }
+
+            void indent(int n) {
+                indent += n;
+            }
+
+            String compress(String s) {
+                s = s.replace("\n", "|").replace(" ", "_");
+                return (s.length() < 32)
+                        ? s
+                        : s.substring(0, 16) + "..." + s.substring(16);
+            }
+
+            String quote(String s) {
+                if (s.contains("\""))
+                    return "'" + s + "'";
+                else if (s.contains("'") || s.contains(" "))
+                    return '"' + s + '"';
+                else
+                    return s;
+            }
+
+
+        }
+    }
+
+    /**
+     * Verify the reported tree positions by comparing the characters found
+     * at and after the reported position with the beginning of the pretty-
+     * printed text.
+     */
+    static class PosChecker extends Checker {
+        PosChecker(DocCommentTester test, DocTrees t) {
+            test.super(t);
+        }
+
+        @Override
+        void check(TreePath path, Name name) throws Exception {
+            JavaFileObject fo = path.getCompilationUnit().getSourceFile();
+            final CharSequence cs = fo.getCharContent(true);
+
+            final DCDocComment dc = (DCDocComment) trees.getDocCommentTree(path);
+            DCTree t = (DCTree) trees.getDocCommentTree(path);
+
+            DocTreeScanner scanner = new DocTreeScanner<Void,Void>() {
+                @Override
+                public Void scan(DocTree node, Void ignore) {
+                    if (node != null) {
+                        try {
+                            String expect = getExpectText(node);
+                            long pos = ((DCTree) node).getSourcePosition(dc);
+                            String found = getFoundText(cs, (int) pos, expect.length());
+                            if (!found.equals(expect)) {
+                                System.err.println("expect: " + expect);
+                                System.err.println("found:  " + found);
+                                error("mismatch");
+                            }
+
+                        } catch (StringIndexOutOfBoundsException e) {
+                            error(node.getClass() + ": " + e.toString());
+                                e.printStackTrace();
+                        }
+                    }
+                    return super.scan(node, ignore);
+                }
+            };
+
+            scanner.scan(t, null);
+        }
+
+        String getExpectText(DocTree t) {
+            StringWriter sw = new StringWriter();
+            DocPretty p = new DocPretty(sw);
+            try { p.print(t); } catch (IOException never) { }
+            String s = sw.toString();
+            if (s.length() <= 1)
+                return s;
+            int ws = s.replaceAll("\\s+", " ").indexOf(" ");
+            if (ws != -1) s = s.substring(0, ws);
+            return (s.length() < 5) ? s : s.substring(0, 5);
+        }
+
+        String getFoundText(CharSequence cs, int pos, int len) {
+            return (pos == -1) ? "" : cs.subSequence(pos, Math.min(pos + len, cs.length())).toString();
+        }
+    }
+
+    /**
+     * Verify the pretty printed text against a normalized form of the
+     * original doc comment.
+     */
+    static class PrettyChecker extends Checker {
+
+        PrettyChecker(DocCommentTester test, DocTrees t) {
+            test.super(t);
+        }
+
+        @Override
+        void check(TreePath path, Name name) throws Exception {
+            String raw = trees.getDocComment(path);
+            String normRaw = normalize(raw);
+
+            StringWriter out = new StringWriter();
+            DocPretty dp = new DocPretty(out);
+            dp.print(trees.getDocCommentTree(path));
+            String pretty = out.toString();
+
+            if (!pretty.equals(normRaw)) {
+                error("mismatch");
+                System.err.println("*** expected:");
+                System.err.println(normRaw.replace(" ", "_"));
+                System.err.println("*** found:");
+                System.err.println(pretty.replace(" ", "_"));
+    //            throw new Error();
+            }
+        }
+
+        /**
+         * Normalize white space in places where the tree does not preserve it.
+         */
+        String normalize(String s) {
+            return s.trim()
+                    .replaceFirst("\\.\\s++([^@])", ". $1")
+                    .replaceFirst("\\.\\s*\\n *@", ".\n@")
+                    .replaceFirst("\\s+<(/?p|pre|h[1-6])>", " <$1>")
+                    .replaceAll("\\{@docRoot\\s+\\}", "{@docRoot}")
+                    .replaceAll("\\{@inheritDoc\\s+\\}", "{@inheritDoc}")
+                    .replaceAll("(\\{@value\\s+[^}]+)\\s+(\\})", "$1$2")
+                    .replaceAll("\n[ \t]+@", "\n@");
+        }
+
+    }
+
+}
+

langtools/test/tools/javac/doctree/DocRootTest.java

@@ -0,0 +1,84 @@
+/*
+ * Copyright (c) 2012, 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 7021614
+ * @summary extend com.sun.source API to support parsing javadoc comments
+ * @build DocCommentTester
+ * @run main DocCommentTester DocRootTest.java
+ */
+
+class DocRootTest {
+    /** abc {@docRoot} */
+    void standard() { }
+/*
+DocComment[DOC_COMMENT, pos:0
+  firstSentence: 2
+    Text[TEXT, pos:0, abc_]
+    DocRoot[DOC_ROOT, pos:4]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /** abc {@docRoot } */
+    void standard_ws1() { }
+/*
+DocComment[DOC_COMMENT, pos:0
+  firstSentence: 2
+    Text[TEXT, pos:0, abc_]
+    DocRoot[DOC_ROOT, pos:4]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /** abc {@docRoot  } */
+    void standard_ws2() { }
+/*
+DocComment[DOC_COMMENT, pos:0
+  firstSentence: 2
+    Text[TEXT, pos:0, abc_]
+    DocRoot[DOC_ROOT, pos:4]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /** abc {@docRoot junk} */
+    void error() { }
+/*
+DocComment[DOC_COMMENT, pos:0
+  firstSentence: 2
+    Text[TEXT, pos:0, abc_]
+    Erroneous[ERRONEOUS, pos:4
+      code: compiler.err.dc.unexpected.content
+      body: {@docRoot_junk}
+    ]
+  body: empty
+  block tags: empty
+]
+*/
+
+}

langtools/test/tools/javac/doctree/ElementTest.java

@@ -0,0 +1,250 @@
+/*
+ * Copyright (c) 2012, 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 7021614
+ * @summary extend com.sun.source API to support parsing javadoc comments
+ * @build DocCommentTester
+ * @run main DocCommentTester ElementTest.java
+ */
+
+class ElementTest {
+    /**
+     * <p>para</p>
+     */
+    void simple() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: empty
+  body: 3
+    StartElement[START_ELEMENT, pos:1
+      name:p
+      attributes: empty
+    ]
+    Text[TEXT, pos:4, para]
+    EndElement[END_ELEMENT, pos:8, p]
+  block tags: empty
+]
+*/
+
+    /**
+     * abc <hr/>
+     */
+    void self_closing() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 2
+    Text[TEXT, pos:1, abc_]
+    StartElement[START_ELEMENT, pos:5
+      name:hr
+      attributes: empty
+    ]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * abc < def
+     */
+    void bad_lt() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 3
+    Text[TEXT, pos:1, abc_]
+    Erroneous[ERRONEOUS, pos:5
+      code: compiler.err.dc.malformed.html
+      body: <
+    ]
+    Text[TEXT, pos:6, _def]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * abc > def
+     */
+    void bad_gt() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 3
+    Text[TEXT, pos:1, abc_]
+    Erroneous[ERRONEOUS, pos:5
+      code: compiler.err.dc.bad.gt
+      body: >
+    ]
+    Text[TEXT, pos:6, _def]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * abc <p 123> def
+     */
+    void bad_chars_start();
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 5
+    Text[TEXT, pos:1, abc_]
+    Erroneous[ERRONEOUS, pos:5
+      code: compiler.err.dc.malformed.html
+      body: <
+    ]
+    Text[TEXT, pos:6, p_123]
+    Erroneous[ERRONEOUS, pos:11
+      code: compiler.err.dc.bad.gt
+      body: >
+    ]
+    Text[TEXT, pos:12, _def]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * abc </p 123> def
+     */
+    void bad_chars_end();
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 5
+    Text[TEXT, pos:1, abc_]
+    Erroneous[ERRONEOUS, pos:5
+      code: compiler.err.dc.malformed.html
+      body: <
+    ]
+    Text[TEXT, pos:6, /p_123]
+    Erroneous[ERRONEOUS, pos:12
+      code: compiler.err.dc.bad.gt
+      body: >
+    ]
+    Text[TEXT, pos:13, _def]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * abc <hr
+     */
+    void unterminated_eoi() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 3
+    Text[TEXT, pos:1, abc_]
+    Erroneous[ERRONEOUS, pos:5
+      code: compiler.err.dc.malformed.html
+      body: <
+    ]
+    Text[TEXT, pos:6, hr]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * abc <hr
+     * @author jjg
+     */
+    void unterminated_block() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 3
+    Text[TEXT, pos:1, abc_]
+    Erroneous[ERRONEOUS, pos:5
+      code: compiler.err.dc.malformed.html
+      body: <
+    ]
+    Text[TEXT, pos:6, hr]
+  body: empty
+  block tags: 1
+    Author[AUTHOR, pos:10
+      name: 1
+        Text[TEXT, pos:18, jjg]
+    ]
+]
+*/
+
+
+    /**
+     * abc </p
+     */
+    void unterminated_end_eoi() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 3
+    Text[TEXT, pos:1, abc_]
+    Erroneous[ERRONEOUS, pos:5
+      code: compiler.err.dc.malformed.html
+      body: <
+    ]
+    Text[TEXT, pos:6, /p]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * abc </p
+     * @author jjg
+     */
+    void unterminated_end_block() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 3
+    Text[TEXT, pos:1, abc_]
+    Erroneous[ERRONEOUS, pos:5
+      code: compiler.err.dc.malformed.html
+      body: <
+    ]
+    Text[TEXT, pos:6, /p]
+  body: empty
+  block tags: 1
+    Author[AUTHOR, pos:10
+      name: 1
+        Text[TEXT, pos:18, jjg]
+    ]
+]
+*/
+
+    /**
+     * abc
+     * <!-- comment -->
+     * def
+     */
+    void comment() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 3
+    Text[TEXT, pos:1, abc|_]
+    Comment[COMMENT, pos:6, <!--_comment_-->]
+    Text[TEXT, pos:22, |_def]
+  body: empty
+  block tags: empty
+]
+*/
+
+}

langtools/test/tools/javac/doctree/EntityTest.java

@@ -0,0 +1,165 @@
+/*
+ * Copyright (c) 2012, 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 7021614
+ * @summary extend com.sun.source API to support parsing javadoc comments
+ * @build DocCommentTester
+ * @run main DocCommentTester EntityTest.java
+ */
+
+class EntityTest {
+    /**
+     *  abc < def
+     */
+    public void name() { }
+/*
+DocComment[DOC_COMMENT, pos:2
+  firstSentence: 3
+    Text[TEXT, pos:2, abc_]
+    Entity[ENTITY, pos:6, lt]
+    Text[TEXT, pos:10, _def]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     *  abc   def
+     */
+    public void decimal_value() { }
+/*
+DocComment[DOC_COMMENT, pos:2
+  firstSentence: 3
+    Text[TEXT, pos:2, abc_]
+    Entity[ENTITY, pos:6, #160]
+    Text[TEXT, pos:12, _def]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     *  abc   def
+     */
+    public void lower_hex_value() { }
+/*
+DocComment[DOC_COMMENT, pos:2
+  firstSentence: 3
+    Text[TEXT, pos:2, abc_]
+    Entity[ENTITY, pos:6, #xa0]
+    Text[TEXT, pos:12, _def]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     *  abc   def
+     */
+    public void upper_hex_value() { }
+/*
+DocComment[DOC_COMMENT, pos:2
+  firstSentence: 3
+    Text[TEXT, pos:2, abc_]
+    Entity[ENTITY, pos:6, #XA0]
+    Text[TEXT, pos:12, _def]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     *  abc & def
+     */
+    public void bad_amp() { }
+/*
+DocComment[DOC_COMMENT, pos:2
+  firstSentence: 3
+    Text[TEXT, pos:2, abc_]
+    Erroneous[ERRONEOUS, pos:6
+      code: compiler.err.dc.bad.entity
+      body: &
+    ]
+    Text[TEXT, pos:7, _def]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     *  abc &1 def
+     */
+    public void bad_entity_name() { }
+/*
+DocComment[DOC_COMMENT, pos:2
+  firstSentence: 3
+    Text[TEXT, pos:2, abc_]
+    Erroneous[ERRONEOUS, pos:6
+      code: compiler.err.dc.bad.entity
+      body: &
+    ]
+    Text[TEXT, pos:7, 1_def]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     *  abc &#012.3; def
+     */
+    public void bad_entity_decimal_value() { }
+/*
+DocComment[DOC_COMMENT, pos:2
+  firstSentence: 3
+    Text[TEXT, pos:2, abc_]
+    Erroneous[ERRONEOUS, pos:6
+      code: compiler.err.dc.missing.semicolon
+      body: &#012
+    ]
+    Text[TEXT, pos:11, .3;_def]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     *  abc &#x012azc; def
+     */
+    public void bad_entity_hex_value() { }
+/*
+DocComment[DOC_COMMENT, pos:2
+  firstSentence: 3
+    Text[TEXT, pos:2, abc_]
+    Erroneous[ERRONEOUS, pos:6
+      code: compiler.err.dc.missing.semicolon
+      body: &#x012a
+    ]
+    Text[TEXT, pos:13, zc;_def]
+  body: empty
+  block tags: empty
+]
+*/
+
+}

langtools/test/tools/javac/doctree/ExceptionTest.java

@@ -0,0 +1,69 @@
+/*
+ * Copyright (c) 2012, 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 7021614
+ * @summary extend com.sun.source API to support parsing javadoc comments
+ * @build DocCommentTester
+ * @run main DocCommentTester ExceptionTest.java
+ */
+
+class ExceptionTest {
+    /**
+     * @exception Exception
+     */
+    void exception() throws Exception { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: empty
+  body: empty
+  block tags: 1
+    Throws[EXCEPTION, pos:1
+      exceptionName:
+        Reference[REFERENCE, pos:12, Exception]
+      description: empty
+    ]
+]
+*/
+
+    /**
+     * @exception Exception text
+     */
+    void exception_text() throws Exception { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: empty
+  body: empty
+  block tags: 1
+    Throws[EXCEPTION, pos:1
+      exceptionName:
+        Reference[REFERENCE, pos:12, Exception]
+      description: 1
+        Text[TEXT, pos:22, text]
+    ]
+]
+*/
+
+}
+

langtools/test/tools/javac/doctree/FirstSentenceTest.java

@@ -0,0 +1,198 @@
+/*
+ * Copyright (c) 2012, 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 7021614
+ * @summary extend com.sun.source API to support parsing javadoc comments
+ * @build DocCommentTester
+ * @run main DocCommentTester FirstSentenceTest.java
+ */
+
+class FirstSentenceTest {
+    /** */
+    void empty() { }
+/*
+DocComment[DOC_COMMENT, pos:-1
+  firstSentence: empty
+  body: empty
+  block tags: empty
+]
+*/
+
+    /** abc def ghi */
+    void no_terminator() { }
+/*
+DocComment[DOC_COMMENT, pos:0
+  firstSentence: 1
+    Text[TEXT, pos:0, abc_def_ghi]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * abc def ghi.
+     */
+    void no_body() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 1
+    Text[TEXT, pos:1, abc_def_ghi.]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * abc def ghi. jkl mno pqr.
+     */
+    void dot_space() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 1
+    Text[TEXT, pos:1, abc_def_ghi.]
+  body: 1
+    Text[TEXT, pos:14, jkl_mno_pqr.]
+  block tags: empty
+]
+*/
+
+    /**
+     * abc def ghi.
+     * jkl mno pqr
+     */
+    void dot_newline() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 1
+    Text[TEXT, pos:1, abc_def_ghi.]
+  body: 1
+    Text[TEXT, pos:15, jkl_mno_pqr]
+  block tags: empty
+]
+*/
+
+    /**
+     * abc def ghi
+     * <p>jkl mno pqr
+     */
+    void dot_p() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 1
+    Text[TEXT, pos:1, abc_def_ghi]
+  body: 2
+    StartElement[START_ELEMENT, pos:14
+      name:p
+      attributes: empty
+    ]
+    Text[TEXT, pos:17, jkl_mno_pqr]
+  block tags: empty
+]
+*/
+
+    /**
+     * abc def ghi
+     * </p>jkl mno pqr
+     */
+    void dot_end_p() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 1
+    Text[TEXT, pos:1, abc_def_ghi]
+  body: 2
+    EndElement[END_ELEMENT, pos:14, p]
+    Text[TEXT, pos:18, jkl_mno_pqr]
+  block tags: empty
+]
+*/
+
+    /**
+     * abc &lt; ghi. jkl mno pqr.
+     */
+    void entity() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 3
+    Text[TEXT, pos:1, abc_]
+    Entity[ENTITY, pos:5, lt]
+    Text[TEXT, pos:9, _ghi.]
+  body: 1
+    Text[TEXT, pos:15, jkl_mno_pqr.]
+  block tags: empty
+]
+*/
+
+    /**
+     * abc {@code code} ghi. jkl mno pqr.
+     */
+    void inline_tag() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 3
+    Text[TEXT, pos:1, abc_]
+    Literal[CODE, pos:5, code]
+    Text[TEXT, pos:17, _ghi.]
+  body: 1
+    Text[TEXT, pos:23, jkl_mno_pqr.]
+  block tags: empty
+]
+*/
+
+    /**
+     * abc def ghi
+     * @author jjg
+     */
+    void block_tag() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 1
+    Text[TEXT, pos:1, abc_def_ghi]
+  body: empty
+  block tags: 1
+    Author[AUTHOR, pos:14
+      name: 1
+        Text[TEXT, pos:22, jjg]
+    ]
+]
+*/
+
+    /**
+     * @author jjg
+     */
+    void just_tag() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: empty
+  body: empty
+  block tags: 1
+    Author[AUTHOR, pos:1
+      name: 1
+        Text[TEXT, pos:9, jjg]
+    ]
+]
+*/
+
+}
+

langtools/test/tools/javac/doctree/InheritDocTest.java

@@ -0,0 +1,84 @@
+/*
+ * Copyright (c) 2012, 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 7021614
+ * @summary extend com.sun.source API to support parsing javadoc comments
+ * @build DocCommentTester
+ * @run main DocCommentTester InheritDocTest.java
+ */
+
+class InheritDocTest {
+    /** abc {@inheritDoc} */
+    void standard() { }
+/*
+DocComment[DOC_COMMENT, pos:0
+  firstSentence: 2
+    Text[TEXT, pos:0, abc_]
+    InheritDoc[INHERIT_DOC, pos:4]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /** abc {@inheritDoc } */
+    void standard_ws1() { }
+/*
+DocComment[DOC_COMMENT, pos:0
+  firstSentence: 2
+    Text[TEXT, pos:0, abc_]
+    InheritDoc[INHERIT_DOC, pos:4]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /** abc {@inheritDoc  } */
+    void standard_ws2() { }
+/*
+DocComment[DOC_COMMENT, pos:0
+  firstSentence: 2
+    Text[TEXT, pos:0, abc_]
+    InheritDoc[INHERIT_DOC, pos:4]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /** abc {@inheritDoc junk} */
+    void error() { }
+/*
+DocComment[DOC_COMMENT, pos:0
+  firstSentence: 2
+    Text[TEXT, pos:0, abc_]
+    Erroneous[ERRONEOUS, pos:4
+      code: compiler.err.dc.unexpected.content
+      body: {@inheritDoc_junk}
+    ]
+  body: empty
+  block tags: empty
+]
+*/
+
+}

langtools/test/tools/javac/doctree/LinkPlainTest.java

@@ -0,0 +1,192 @@
+/*
+ * Copyright (c) 2012, 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 7021614
+ * @summary extend com.sun.source API to support parsing javadoc comments
+ * @build DocCommentTester
+ * @run main DocCommentTester LinkPlainTest.java
+ */
+
+class LinkPlainTest {
+    /**
+     * abc {@linkplain String} def
+      */
+    void simple_name() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 3
+    Text[TEXT, pos:1, abc_]
+    Link[LINK_PLAIN, pos:5
+      reference:
+        Reference[REFERENCE, pos:17, String]
+      body: empty
+    ]
+    Text[TEXT, pos:24, _def]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * abc {@linkplain String desc} def
+     */
+    void simple_name_desc() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 3
+    Text[TEXT, pos:1, abc_]
+    Link[LINK_PLAIN, pos:5
+      reference:
+        Reference[REFERENCE, pos:17, String]
+      body: 1
+        Text[TEXT, pos:24, desc]
+    ]
+    Text[TEXT, pos:29, _def]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * abc {@linkplain java.lang.String desc} def
+     */
+    void pkg_name_desc() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 3
+    Text[TEXT, pos:1, abc_]
+    Link[LINK_PLAIN, pos:5
+      reference:
+        Reference[REFERENCE, pos:17, java.lang.String]
+      body: 1
+        Text[TEXT, pos:34, desc]
+    ]
+    Text[TEXT, pos:39, _def]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * abc {@linkplain java.lang.String#isEmpty desc} def
+     */
+    void method_desc() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 3
+    Text[TEXT, pos:1, abc_]
+    Link[LINK_PLAIN, pos:5
+      reference:
+        Reference[REFERENCE, pos:17, java.lang.String#isEmpty]
+      body: 1
+        Text[TEXT, pos:42, desc]
+    ]
+    Text[TEXT, pos:47, _def]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * abc {@linkplain java.lang.String#isEmpty() desc} def
+     */
+    void method_0_args_desc() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 3
+    Text[TEXT, pos:1, abc_]
+    Link[LINK_PLAIN, pos:5
+      reference:
+        Reference[REFERENCE, pos:17, java.lang.String#isEmpty()]
+      body: 1
+        Text[TEXT, pos:44, desc]
+    ]
+    Text[TEXT, pos:49, _def]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * abc {@linkplain java.lang.String#substring(int) desc} def
+     */
+    void method_1_args_desc() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 3
+    Text[TEXT, pos:1, abc_]
+    Link[LINK_PLAIN, pos:5
+      reference:
+        Reference[REFERENCE, pos:17, java.lang.String#substring(int)]
+      body: 1
+        Text[TEXT, pos:49, desc]
+    ]
+    Text[TEXT, pos:54, _def]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * abc {@linkplain java.lang.String#substring(int, int) desc} def
+     */
+    void method_2_args_desc() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 3
+    Text[TEXT, pos:1, abc_]
+    Link[LINK_PLAIN, pos:5
+      reference:
+        Reference[REFERENCE, pos:17, java.lang.String...#substring(int,_int)]
+      body: 1
+        Text[TEXT, pos:54, desc]
+    ]
+    Text[TEXT, pos:59, _def]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * abc {@linkplain java.util.List<T> desc} def
+     */
+    void pkg_name_typarams_desc() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 3
+    Text[TEXT, pos:1, abc_]
+    Link[LINK_PLAIN, pos:5
+      reference:
+        Reference[REFERENCE, pos:17, java.util.List<T>]
+      body: 1
+        Text[TEXT, pos:35, desc]
+    ]
+    Text[TEXT, pos:40, _def]
+  body: empty
+  block tags: empty
+]
+*/
+
+}

langtools/test/tools/javac/doctree/LinkTest.java

@@ -0,0 +1,192 @@
+/*
+ * Copyright (c) 2012, 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 7021614
+ * @summary extend com.sun.source API to support parsing javadoc comments
+ * @build DocCommentTester
+ * @run main DocCommentTester LinkTest.java
+ */
+
+class LinkTest {
+    /**
+     * abc {@link String} def
+      */
+    void simple_name() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 3
+    Text[TEXT, pos:1, abc_]
+    Link[LINK, pos:5
+      reference:
+        Reference[REFERENCE, pos:12, String]
+      body: empty
+    ]
+    Text[TEXT, pos:19, _def]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * abc {@link String desc} def
+     */
+    void simple_name_desc() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 3
+    Text[TEXT, pos:1, abc_]
+    Link[LINK, pos:5
+      reference:
+        Reference[REFERENCE, pos:12, String]
+      body: 1
+        Text[TEXT, pos:19, desc]
+    ]
+    Text[TEXT, pos:24, _def]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * abc {@link java.lang.String desc} def
+     */
+    void pkg_name_desc() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 3
+    Text[TEXT, pos:1, abc_]
+    Link[LINK, pos:5
+      reference:
+        Reference[REFERENCE, pos:12, java.lang.String]
+      body: 1
+        Text[TEXT, pos:29, desc]
+    ]
+    Text[TEXT, pos:34, _def]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * abc {@link java.lang.String#isEmpty desc} def
+     */
+    void method_desc() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 3
+    Text[TEXT, pos:1, abc_]
+    Link[LINK, pos:5
+      reference:
+        Reference[REFERENCE, pos:12, java.lang.String#isEmpty]
+      body: 1
+        Text[TEXT, pos:37, desc]
+    ]
+    Text[TEXT, pos:42, _def]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * abc {@link java.lang.String#isEmpty() desc} def
+     */
+    void method_0_args_desc() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 3
+    Text[TEXT, pos:1, abc_]
+    Link[LINK, pos:5
+      reference:
+        Reference[REFERENCE, pos:12, java.lang.String#isEmpty()]
+      body: 1
+        Text[TEXT, pos:39, desc]
+    ]
+    Text[TEXT, pos:44, _def]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * abc {@link java.lang.String#substring(int) desc} def
+     */
+    void method_1_args_desc() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 3
+    Text[TEXT, pos:1, abc_]
+    Link[LINK, pos:5
+      reference:
+        Reference[REFERENCE, pos:12, java.lang.String#substring(int)]
+      body: 1
+        Text[TEXT, pos:44, desc]
+    ]
+    Text[TEXT, pos:49, _def]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * abc {@link java.lang.String#substring(int, int) desc} def
+     */
+    void method_2_args_desc() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 3
+    Text[TEXT, pos:1, abc_]
+    Link[LINK, pos:5
+      reference:
+        Reference[REFERENCE, pos:12, java.lang.String...#substring(int,_int)]
+      body: 1
+        Text[TEXT, pos:49, desc]
+    ]
+    Text[TEXT, pos:54, _def]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * abc {@link java.util.List<T> desc} def
+     */
+    void pkg_name_typarams_desc() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 3
+    Text[TEXT, pos:1, abc_]
+    Link[LINK, pos:5
+      reference:
+        Reference[REFERENCE, pos:12, java.util.List<T>]
+      body: 1
+        Text[TEXT, pos:30, desc]
+    ]
+    Text[TEXT, pos:35, _def]
+  body: empty
+  block tags: empty
+]
+*/
+
+}

langtools/test/tools/javac/doctree/LiteralTest.java

@@ -0,0 +1,134 @@
+/*
+ * Copyright (c) 2012, 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 7021614
+ * @summary extend com.sun.source API to support parsing javadoc comments
+ * @build DocCommentTester
+ * @run main DocCommentTester LiteralTest.java
+ */
+
+class LiteralTest {
+    /** {@literal if (a < b) { }} */
+    void minimal() { }
+/*
+DocComment[DOC_COMMENT, pos:0
+  firstSentence: 1
+    Literal[LITERAL, pos:0, if_(a_<_b)_{_}]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /** [{@literal if (a < b) { }}] */
+    void in_brackets() { }
+/*
+DocComment[DOC_COMMENT, pos:0
+  firstSentence: 3
+    Text[TEXT, pos:0, []
+    Literal[LITERAL, pos:1, if_(a_<_b)_{_}]
+    Text[TEXT, pos:26, ]]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /** [ {@literal if (a < b) { }} ] */
+    void in_brackets_with_whitespace() { }
+/*
+DocComment[DOC_COMMENT, pos:0
+  firstSentence: 3
+    Text[TEXT, pos:0, [_]
+    Literal[LITERAL, pos:2, if_(a_<_b)_{_}]
+    Text[TEXT, pos:27, _]]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * {@literal {@literal nested} }
+     */
+    void nested() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 1
+    Literal[LITERAL, pos:1, {@literal_nested}_]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * {@literal if (a < b) {
+     *        }
+     * }
+     */
+    void embedded_newline() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 1
+    Literal[LITERAL, pos:1, if_(a_<_b)_{|________}|_]
+  body: empty
+  block tags: empty
+]
+*/
+
+
+    /** {@literal if (a < b) { } */
+    void unterminated_1() { }
+/*
+DocComment[DOC_COMMENT, pos:0
+  firstSentence: 1
+    Erroneous[ERRONEOUS, pos:0
+      code: compiler.err.dc.unterminated.inline.tag
+      body: {@literal_if_(a_<_b)_{_}
+    ]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * {@literal if (a < b) { }
+     * @author jjg */
+    void unterminated_2() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 1
+    Erroneous[ERRONEOUS, pos:1
+      code: compiler.err.dc.unterminated.inline.tag
+      body: {@literal_if_(a_<_b)_{_}
+    ]
+  body: empty
+  block tags: 1
+    Author[AUTHOR, pos:27
+      name: 1
+        Text[TEXT, pos:35, jjg]
+    ]
+]
+*/
+
+}
+

langtools/test/tools/javac/doctree/ParamTest.java

@@ -0,0 +1,68 @@
+/*
+ * Copyright (c) 2012, 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 7021614
+ * @summary extend com.sun.source API to support parsing javadoc comments
+ * @build DocCommentTester
+ * @run main DocCommentTester ParamTest.java
+ */
+
+class ParamTest {
+    /**
+     * @param x
+     */
+    void no_description(int x) { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: empty
+  body: empty
+  block tags: 1
+    Param[PARAM, pos:1
+      name:
+        Identifier[IDENTIFIER, pos:8, x]
+      description: empty
+    ]
+]
+*/
+
+    /**
+     * @param x description
+     */
+    void with_description(int x) { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: empty
+  body: empty
+  block tags: 1
+    Param[PARAM, pos:1
+      name:
+        Identifier[IDENTIFIER, pos:8, x]
+      description: 1
+        Text[TEXT, pos:10, description]
+    ]
+]
+*/
+
+}

langtools/test/tools/javac/doctree/ReferenceTest.java

@@ -0,0 +1,214 @@
+/*
+ * Copyright (c) 2012, 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 7021614
+ * @summary extend com.sun.source API to support parsing javadoc comments
+ * @summary check references in at-see and {at-link} tags
+ * @build ReferenceTest
+ * @compile -processor ReferenceTest -proc:only ReferenceTest.java
+ */
+
+import com.sun.source.doctree.DocCommentTree;
+import com.sun.source.doctree.DocTree;
+import com.sun.source.doctree.LinkTree;
+import com.sun.source.doctree.ReferenceTree;
+import com.sun.source.doctree.SeeTree;
+import com.sun.source.doctree.TextTree;
+import com.sun.source.util.DocTreeScanner;
+import com.sun.source.util.DocTrees;
+import com.sun.source.util.TreePath;
+
+import java.util.List;
+import java.util.Set;
+import javax.annotation.processing.AbstractProcessor;
+import javax.annotation.processing.ProcessingEnvironment;
+import javax.annotation.processing.RoundEnvironment;
+import javax.annotation.processing.SupportedAnnotationTypes;
+import javax.lang.model.SourceVersion;
+import javax.lang.model.element.Element;
+import javax.lang.model.element.TypeElement;
+import javax.tools.Diagnostic.Kind;
+
+/**
+ * {@link java.lang        Package}
+ * {@link java.lang.ERROR  Bad}
+ *
+ * {@link java.lang.String Class}
+ * {@link           String Class}
+ * {@link java.lang.String#CASE_INSENSITIVE_ORDER Field}
+ * {@link java.lang.String#String Constructor}
+ * {@link java.lang.String#String(byte[]) Constructor}
+ * {@link java.lang.String#String(byte[] bytes) Constructor}
+ * {@link java.lang.String#String(byte[], String) Constructor}
+ * {@link java.lang.String#String(byte[] bytes, String charSetName) Constructor}
+ * {@link java.lang.String#isEmpty Method}
+ * {@link java.lang.String#isEmpty() Method}
+ * {@link java.lang.String#ERROR Bad}
+ * {@link java.lang.String#equals(Object) Method}
+ *
+ * {@link AbstractProcessor Class}
+ *
+ * {@link List#add(Object) Method}
+ *
+ * {@link #trees Field}
+ * {@link #getSupportedSourceVersion Method}
+ * {@link #init(ProcessingEnvironment Method}
+ *
+ * @see java.lang        Package
+ * @see java.lang.ERROR  Bad
+ *
+ * @see java.lang.String Class
+ * @see           String Class
+ * @see java.lang.String#CASE_INSENSITIVE_ORDER Field
+ * @see java.lang.String#String Constructor
+ * @see java.lang.String#String(byte[]) Constructor
+ * @see java.lang.String#String(byte[] bytes) Constructor
+ * @see java.lang.String#String(byte[],String) Constructor
+ * @see java.lang.String#String(byte[] bytes, String charsetName) Constructor
+ * @see java.lang.String#isEmpty Method
+ * @see java.lang.String#isEmpty() Method
+ * @see java.lang.String#ERROR Bad
+ * @see java.lang.String#equals(Object) Method
+ *
+ * @see AbstractProcessor Class
+ *
+ * @see List#add(Object) Method
+ *
+ * @see #trees Field
+ * @see #getSupportedSourceVersion Method
+ * @see #init(ProcessingEnvironment) Method
+ *
+ * @see java.io.BufferedInputStream#BufferedInputStream(InputStream) Constructor
+ */
+@SupportedAnnotationTypes("*")
+public class ReferenceTest extends AbstractProcessor {
+    DocTrees trees;
+
+    @Override
+    public SourceVersion getSupportedSourceVersion() {
+        return SourceVersion.latest();
+    }
+
+    @Override
+    public void init(ProcessingEnvironment pEnv) {
+        super.init(pEnv);
+        trees = DocTrees.instance(pEnv);
+    }
+
+    @Override
+    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
+        for (Element e: roundEnv.getRootElements()) {
+            new DocCommentScanner(trees.getPath(e)).scan();
+        }
+        return true;
+    }
+
+    class DocCommentScanner extends DocTreeScanner<Void, Void> {
+        TreePath path;
+        DocCommentTree dc;
+
+        DocCommentScanner(TreePath path) {
+            this.path = path;
+        }
+
+        void scan() {
+            dc = trees.getDocCommentTree(path);
+            scan(dc, null);
+        }
+
+        @Override
+        public Void visitLink(LinkTree tree, Void ignore) {
+            checkReference(tree.getReference(), tree.getLabel());
+            return null;
+        }
+
+        @Override
+        public Void visitSee(SeeTree tree, Void ignore) {
+            List<? extends DocTree> refLabel = tree.getReference();
+            if (refLabel.size() > 1 && (refLabel.get(0) instanceof ReferenceTree)) {
+                ReferenceTree ref = (ReferenceTree) refLabel.get(0);
+                List<? extends DocTree> label = refLabel.subList(1, refLabel.size());
+                checkReference(ref, label);
+            }
+            return null;
+        }
+
+        void checkReference(ReferenceTree tree, List<? extends DocTree> label) {
+            String sig = tree.getSignature();
+
+            Element found = trees.getElement(path, tree);
+            if (found == null) {
+                System.err.println(sig + " NOT FOUND");
+            } else {
+                System.err.println(sig + " found " + found.getKind() + " " + found);
+            }
+
+            String expect = "UNKNOWN";
+            if (label.size() > 0 && label.get(0) instanceof TextTree)
+                expect = ((TextTree) label.get(0)).getBody();
+
+            if (!expect.equalsIgnoreCase(found == null ? "bad" : found.getKind().name())) {
+                error(tree, "Unexpected value found: " + found +", expected: " + expect);
+            }
+        }
+
+        void error(DocTree tree, String msg) {
+            trees.printMessage(Kind.ERROR, msg, tree, dc, path.getCompilationUnit());
+        }
+    }
+}
+
+/**
+ * @see ReferenceTestExtras    Class
+ * @see #ReferenceTestExtras   Field
+ * @see #ReferenceTestExtras() Constructor
+ *
+ * @see #X    Field
+ * @see #X()  Method
+ *
+ * @see #m    Method
+ *
+ * @see #varargs(int...)        Method
+ * @see #varargs(int... args)   Method
+ * @see #varargs(int[])         Method
+ * @see #varargs(int[] args)    Method
+ */
+class ReferenceTestExtras {
+    int ReferenceTestExtras;            // field
+    ReferenceTestExtras() { }           // constructor
+    void ReferenceTestExtras() { }      // method
+
+    int X;
+    void X() { }
+    static class X { }
+
+    void m() { }
+    void m(int i) { }
+    void m(int i, int j) { }
+
+    void varargs(int... args) { }
+}
+
+

langtools/test/tools/javac/doctree/ReturnTest.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright (c) 2012, 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 7021614
+ * @summary extend com.sun.source API to support parsing javadoc comments
+ * @build DocCommentTester
+ * @run main DocCommentTester ReturnTest.java
+ */
+
+class ReturnTest {
+    /**
+     * @return something
+     */
+    int an_int() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: empty
+  body: empty
+  block tags: 1
+    Return[RETURN, pos:1
+      description: 1
+        Text[TEXT, pos:9, something]
+    ]
+]
+*/
+
+}
+
+

langtools/test/tools/javac/doctree/SeeTest.java

@@ -0,0 +1,174 @@
+/*
+ * Copyright (c) 2012, 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 7021614
+ * @summary extend com.sun.source API to support parsing javadoc comments
+ * @build DocCommentTester
+ * @run main DocCommentTester SeeTest.java
+ */
+
+class SeeTest {
+    /**
+     * abc.
+     * @see "String"
+     */
+    void quoted_text() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 1
+    Text[TEXT, pos:1, abc.]
+  body: empty
+  block tags: 1
+    Erroneous[ERRONEOUS, pos:7
+      code: compiler.err.dc.unexpected.content
+      body: @see_"String"
+    ]
+]
+*/
+
+    /**
+     * abc.
+     * @see <a href="url">url</a>
+     */
+    void url() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 1
+    Text[TEXT, pos:1, abc.]
+  body: empty
+  block tags: 1
+    See[SEE, pos:7
+      reference: 3
+        StartElement[START_ELEMENT, pos:12
+          name:a
+          attributes: 1
+            Attribute[ATTRIBUTE, pos:15
+              name: href
+              vkind: DOUBLE
+              value: 1
+                Text[TEXT, pos:21, url]
+            ]
+        ]
+        Text[TEXT, pos:26, url]
+        EndElement[END_ELEMENT, pos:29, a]
+    ]
+]
+*/
+
+    /**
+     * abc.
+     * @see String text
+     */
+    void string() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 1
+    Text[TEXT, pos:1, abc.]
+  body: empty
+  block tags: 1
+    See[SEE, pos:7
+      reference: 2
+        Reference[REFERENCE, pos:12, String]
+        Text[TEXT, pos:19, text]
+    ]
+]
+*/
+
+    /**
+     * abc.
+     * @see java.lang.String text
+     */
+    void j_l_string() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 1
+    Text[TEXT, pos:1, abc.]
+  body: empty
+  block tags: 1
+    See[SEE, pos:7
+      reference: 2
+        Reference[REFERENCE, pos:12, java.lang.String]
+        Text[TEXT, pos:29, text]
+    ]
+]
+*/
+
+    /**
+     * abc.
+     * @see java.lang.String#length text
+     */
+    void j_l_string_length() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 1
+    Text[TEXT, pos:1, abc.]
+  body: empty
+  block tags: 1
+    See[SEE, pos:7
+      reference: 2
+        Reference[REFERENCE, pos:12, java.lang.String#length]
+        Text[TEXT, pos:36, text]
+    ]
+]
+*/
+
+    /**
+     * abc.
+     * @see java.lang.String#matches(String regex) text
+     */
+    void j_l_string_matches() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 1
+    Text[TEXT, pos:1, abc.]
+  body: empty
+  block tags: 1
+    See[SEE, pos:7
+      reference: 2
+        Reference[REFERENCE, pos:12, java.lang.String...#matches(String_regex)]
+        Text[TEXT, pos:51, text]
+    ]
+]
+*/
+
+    /**
+     * abc.
+     * @see 123 text
+     */
+    void bad_numeric() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 1
+    Text[TEXT, pos:1, abc.]
+  body: empty
+  block tags: 1
+    Erroneous[ERRONEOUS, pos:7
+      code: compiler.err.dc.unexpected.content
+      body: @see_123_text
+    ]
+]
+*/
+
+}

langtools/test/tools/javac/doctree/SerialDataTest.java

@@ -0,0 +1,50 @@
+/*
+ * Copyright (c) 2012, 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 7021614
+ * @summary extend com.sun.source API to support parsing javadoc comments
+ * @build DocCommentTester
+ * @run main DocCommentTester SerialDataTest.java
+ */
+
+class SerialDataTest {
+    /**
+     * @serialData description
+     */
+    void writeObject(ObjectOutputStream stream) { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: empty
+  body: empty
+  block tags: 1
+    SerialData[SERIAL_DATA, pos:1
+      description: 1
+        Text[TEXT, pos:13, description]
+    ]
+]
+*/
+
+}
+

langtools/test/tools/javac/doctree/SerialFieldTest.java

@@ -0,0 +1,74 @@
+/*
+ * Copyright (c) 2012, 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 7021614
+ * @summary extend com.sun.source API to support parsing javadoc comments
+ * @build DocCommentTester
+ * @run main DocCommentTester SerialFieldTest.java
+ */
+
+class SerialFieldTest {
+
+    /**
+     * @serialField field String
+     */
+    String f1;
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: empty
+  body: empty
+  block tags: 1
+    SerialField[SERIAL_FIELD, pos:1
+      name:
+        Identifier[IDENTIFIER, pos:14, field]
+      type:
+        Reference[REFERENCE, pos:20, String]
+      description: empty
+    ]
+]
+*/
+
+    /**
+     * @serialField field String f2 is a String
+     */
+    String f2;
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: empty
+  body: empty
+  block tags: 1
+    SerialField[SERIAL_FIELD, pos:1
+      name:
+        Identifier[IDENTIFIER, pos:14, field]
+      type:
+        Reference[REFERENCE, pos:20, String]
+      description: 1
+        Text[TEXT, pos:27, f2_is_a_String]
+    ]
+]
+*/
+
+}
+

langtools/test/tools/javac/doctree/SerialTest.java

@@ -0,0 +1,97 @@
+/*
+ * Copyright (c) 2012, 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 7021614
+ * @summary extend com.sun.source API to support parsing javadoc comments
+ * @build DocCommentTester
+ * @run main DocCommentTester SerialTest.java
+ */
+
+class SerialTest {
+    /**
+     * @serial include
+     */
+    void include() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: empty
+  body: empty
+  block tags: 1
+    Serial[SERIAL, pos:1
+      description: 1
+        Text[TEXT, pos:9, include]
+    ]
+]
+*/
+
+    /**
+     * @serial exclude
+     */
+    void exclude() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: empty
+  body: empty
+  block tags: 1
+    Serial[SERIAL, pos:1
+      description: 1
+        Text[TEXT, pos:9, exclude]
+    ]
+]
+*/
+
+    /**
+     * @serial description
+     */
+    void description() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: empty
+  body: empty
+  block tags: 1
+    Serial[SERIAL, pos:1
+      description: 1
+        Text[TEXT, pos:9, description]
+    ]
+]
+*/
+
+    /**
+     * @serial
+     */
+    void empty() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: empty
+  body: empty
+  block tags: 1
+    Serial[SERIAL, pos:1
+      description: empty
+    ]
+]
+*/
+
+}
+

langtools/test/tools/javac/doctree/SimpleDocTreeVisitorTest.java

@@ -0,0 +1,166 @@
+/*
+ * Copyright (c) 2012, 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 7021614
+ * @summary extend com.sun.source API to support parsing javadoc comments
+ */
+
+import com.sun.source.doctree.DocCommentTree;
+import com.sun.source.doctree.DocTree;
+import com.sun.source.doctree.DocTreeVisitor;
+import com.sun.source.tree.ClassTree;
+import com.sun.source.tree.CompilationUnitTree;
+import com.sun.source.tree.MethodTree;
+import com.sun.source.tree.Tree;
+import com.sun.source.tree.VariableTree;
+import com.sun.source.util.DocTreeScanner;
+import com.sun.source.util.DocTrees;
+import com.sun.source.util.JavacTask;
+import com.sun.source.util.SimpleDocTreeVisitor;
+import com.sun.source.util.TreePath;
+import com.sun.source.util.TreePathScanner;
+import com.sun.tools.javac.api.JavacTool;
+import java.io.File;
+import java.util.ArrayList;
+import java.util.EnumSet;
+import java.util.List;
+import java.util.Set;
+import javax.lang.model.element.Name;
+import javax.tools.JavaFileObject;
+import javax.tools.StandardJavaFileManager;
+
+public class SimpleDocTreeVisitorTest {
+    public static void main(String... args) throws Exception {
+        SimpleDocTreeVisitorTest t = new SimpleDocTreeVisitorTest();
+        t.run();
+    }
+
+    void run() throws Exception {
+        List<File> files = new ArrayList<File>();
+        File testSrc = new File(System.getProperty("test.src"));
+        for (File f: testSrc.listFiles()) {
+            if (f.isFile() && f.getName().endsWith(".java"))
+                files.add(f);
+        }
+
+        JavacTool javac = JavacTool.create();
+        StandardJavaFileManager fm = javac.getStandardFileManager(null, null, null);
+
+        Iterable<? extends JavaFileObject> fos = fm.getJavaFileObjectsFromFiles(files);
+
+        JavacTask t = javac.getTask(null, fm, null, null, null, fos);
+        DocTrees trees = DocTrees.instance(t);
+
+        Iterable<? extends CompilationUnitTree> units = t.parse();
+
+        Set<DocTree.Kind> found = EnumSet.noneOf(DocTree.Kind.class);
+        DeclScanner ds = new DeclScanner(trees, found);
+        for (CompilationUnitTree unit: units) {
+            ds.scan(unit, null);
+        }
+
+        for (DocTree.Kind k: DocTree.Kind.values()) {
+            if (!found.contains(k) && k != DocTree.Kind.OTHER)
+                error("not found: " + k);
+        }
+
+        if (errors > 0)
+            throw new Exception(errors + " errors occurred");
+    }
+
+    void error(String msg) {
+        System.err.println("Error: " + msg);
+        errors++;
+    }
+
+    int errors;
+
+    static class DeclScanner extends TreePathScanner<Void, Void> {
+        DocTrees trees;
+        DocTreeScanner<Void,Void> cs;
+
+        DeclScanner(DocTrees trees, final Set<DocTree.Kind> found) {
+            this.trees = trees;
+            cs = new CommentScanner(found);
+        }
+
+        @Override
+        public Void visitClass(ClassTree tree, Void ignore) {
+            super.visitClass(tree, ignore);
+            visitDecl(tree, tree.getSimpleName());
+            return null;
+        }
+
+        @Override
+        public Void visitMethod(MethodTree tree, Void ignore) {
+            super.visitMethod(tree, ignore);
+            visitDecl(tree, tree.getName());
+            return null;
+        }
+
+        @Override
+        public Void visitVariable(VariableTree tree, Void ignore) {
+            super.visitVariable(tree, ignore);
+            visitDecl(tree, tree.getName());
+            return null;
+        }
+
+        void visitDecl(Tree tree, Name name) {
+            TreePath path = getCurrentPath();
+            DocCommentTree dc = trees.getDocCommentTree(path);
+            if (dc != null)
+                cs.scan(dc, null);
+        }
+    }
+
+    static class CommentScanner extends DocTreeScanner<Void, Void> {
+        DocTreeVisitor<Void, Void> visitor;
+
+        CommentScanner(Set<DocTree.Kind> found) {
+            visitor = new Visitor(found);
+        }
+
+        @Override
+        public Void scan(DocTree tree, Void ignore) {
+            if (tree != null)
+                tree.accept(visitor, ignore);
+            return super.scan(tree, ignore);
+        }
+    }
+
+    static class Visitor extends SimpleDocTreeVisitor<Void, Void> {
+        Set<DocTree.Kind> found;
+
+        Visitor(Set<DocTree.Kind> found) {
+            this.found = found;
+        }
+
+        @Override
+        public Void defaultAction(DocTree tree, Void ignore) {
+            found.add(tree.getKind());
+            return null;
+        }
+    }
+}

langtools/test/tools/javac/doctree/SinceTest.java

@@ -0,0 +1,53 @@
+/*
+ * Copyright (c) 2012, 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 7021614
+ * @summary extend com.sun.source API to support parsing javadoc comments
+ * @build DocCommentTester
+ * @run main DocCommentTester SinceTest.java
+ */
+
+class SinceTest {
+    /**
+     * abc.
+     * @since then & now.
+     */
+    void standard() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 1
+    Text[TEXT, pos:1, abc.]
+  body: empty
+  block tags: 1
+    Since[SINCE, pos:7
+      body: 3
+        Text[TEXT, pos:14, then_]
+        Entity[ENTITY, pos:19, amp]
+        Text[TEXT, pos:24, _now.]
+    ]
+]
+*/
+
+}

langtools/test/tools/javac/doctree/TagTest.java

@@ -0,0 +1,149 @@
+/*
+ * Copyright (c) 2012, 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 7021614
+ * @summary extend com.sun.source API to support parsing javadoc comments
+ * @build DocCommentTester
+ * @run main DocCommentTester TagTest.java
+ */
+
+class TagTest {
+    /**
+     * @author jjg
+     */
+    void simple_standard_block() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: empty
+  body: empty
+  block tags: 1
+    Author[AUTHOR, pos:1
+      name: 1
+        Text[TEXT, pos:9, jjg]
+    ]
+]
+*/
+
+    /**
+     * @ abc
+     */
+    void no_name_block() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: empty
+  body: empty
+  block tags: 1
+    Erroneous[ERRONEOUS, pos:1
+      code: compiler.err.dc.no.tag.name
+      body: @_abc
+    ]
+]
+*/
+
+    /**
+     * @abc def ghi
+     */
+    void unknown_name_block() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: empty
+  body: empty
+  block tags: 1
+    UnknownBlockTag[UNKNOWN_BLOCK_TAG, pos:1
+      tag:abc
+      content: 1
+        Text[TEXT, pos:6, def_ghi]
+    ]
+]
+*/
+
+    /**
+     * {@link String}
+     */
+    void simple_standard_inline() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 1
+    Link[LINK, pos:1
+      reference:
+        Reference[REFERENCE, pos:8, String]
+      body: empty
+    ]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * {@ abc}
+     */
+    void no_name_inline() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 2
+    Erroneous[ERRONEOUS, pos:1
+      code: compiler.err.dc.no.tag.name
+      body: {@
+    ]
+    Text[TEXT, pos:3, _abc}]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * {@abc def ghi}
+     */
+    void unknown_name_inline() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 1
+    UnknownInlineTag[UNKNOWN_INLINE_TAG, pos:1
+      tag:abc
+      content: 1
+        Text[TEXT, pos:7, def_ghi]
+    ]
+  body: empty
+  block tags: empty
+]
+*/
+
+    /**
+     * {@abc def ghi
+     */
+    void unterminated_standard_inline() { }
+/*
+DocComment[DOC_COMMENT, pos:1
+  firstSentence: 1
+    Erroneous[ERRONEOUS, pos:1
+      code: compiler.err.dc.unterminated.inline.tag
+      body: {@abc_def_ghi
+    ]
+  body: empty
+  block tags: empty
+]
+*/
+
+}