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

Reviewed-by: ksrini, strarup

make/build.xml

 <?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">

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

+/*
+ * 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();
+}

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

+/*
+ * 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();
+}

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

+/*
+ * 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();
+}

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

+/*
+ * 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();
+}
+

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

+/*
+ * 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();
+}

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

+/*
+ * 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();
+}

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

+/*
+ * 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 { }

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

+/*
+ * 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);
+}

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

+/*
+ * 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);
+}

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

+/*
+ * 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();
+}

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

+/*
+ * 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();
+}

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

+/*
+ * 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();
+}

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

+/*
+ * 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();
+}

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

+/*
+ * 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 { }

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

+/*
+ * 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();
+}

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

+/*
+ * 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();
+}

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

+/*
+ * 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();
+}

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

+/*
+ * 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();
+}

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

+/*
+ * 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();
+}

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

+/*
+ * 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();
+}

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

+/*
+ * 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();
+}

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

+/*
+ * 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();
+}

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

+/*
+ * 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();
+}

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

+/*
+ * 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();
+}

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

+/*
+ * 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();
+}

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

+/*
+ * 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();
+}

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

+/*
+ * 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();
+}

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

+/*
+ * 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();
+}

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

+/*
+ * 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();
+}

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

+/*
+ * 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();
+}

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

+/*
+ * 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();
+}

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

+/*
+ * 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();
+}

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

+/*
+ * 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;

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

 /*
- * 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);
 }

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

+/*
+ * 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;
+    }
+
+}

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

+/*
+ * 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);
+}

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

+/*
+ * 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);
+    }
+
+}

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

 /*
- * 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);
 

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 {

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;
     }

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() + "]";
     }

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

 /*
- * 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) + "]";
     }

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).
      */

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) {
-        return keepDocComments ? new SimpleDocCommentTable() : null;
+    protected DocCommentTable newDocCommentTable(boolean keepDocComments, ParserFactory fac) {
+        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();
     }

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) {

src/share/classes/com/sun/tools/javac/parser/SimpleDocCommentTable.java → 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 {
-    Map<JCTree, Comment> table;
+public class LazyDocCommentTable implements DocCommentTable {
+    private static class Entry {
+        final Comment comment;
+        DCDocComment tree;
 
-    SimpleDocCommentTable() {
-        table = new HashMap<JCTree, Comment>();
+        Entry(Comment c) {
+            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));
     }
 
 }

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

 /*
- * 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);
     }

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
+
 

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.
      */

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

+/*
+ * 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;
+    }
+}

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);

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) .

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.
  */

test/tools/javac/diags/DocCommentProcessor.java

+/*
+ * 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;
+}

test/tools/javac/diags/Example.java

 /*
- * 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) {