8046614: Fill in missing doc comments

Reviewed-by: darcy

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2014, 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
@@ -35,10 +35,36 @@ import javax.lang.model.element.Name;
  */
 @jdk.Exported
 public interface AttributeTree extends DocTree {
+    /**
+     * The kind of an attribute value.
+     */
     @jdk.Exported
-    enum ValueKind { EMPTY, UNQUOTED, SINGLE, DOUBLE }
+    enum ValueKind {
+        /** The attribute value is empty. */
+        EMPTY,
+        /** The attribute value is not enclosed in quotes. */
+        UNQUOTED,
+        /** The attribute value is enclosed in single quotation marks. */
+        SINGLE,
+        /** The attribute value is enclosed in double quotation marks. */
+        DOUBLE
+    }
 
+    /**
+     * Returns the name of the attribute.
+     * @return the name of the attribute
+     */
     Name getName();
+
+    /**
+     * Returns the kind of the attribute.
+     * @return the kind of the attribute.
+     */
     ValueKind getValueKind();
+
+    /**
+     * Returns the value of the attribute, or {@code null} if the kind is EMPTY.
+     * @return the value of the attribute.
+     */
     List<? extends DocTree> getValue();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2014, 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
@@ -37,5 +37,9 @@ import java.util.List;
  */
 @jdk.Exported
 public interface AuthorTree extends BlockTagTree {
+    /**
+     * Returns the name of the author.
+     * @return the name
+     */
     List<? extends DocTree> getName();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2014, 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
@@ -33,5 +33,9 @@ package com.sun.source.doctree;
  */
 @jdk.Exported
 public interface BlockTagTree extends DocTree {
+    /**
+     * Returns the name of the tag.
+     * @return the name of the tag
+     */
     String getTagName();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2014, 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
@@ -35,6 +35,10 @@ package com.sun.source.doctree;
  */
 @jdk.Exported
 public interface CommentTree extends DocTree {
+    /**
+     * Returns the text of the comment.
+     * @return the comment text
+     */
     String getBody();
 }
 

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2014, 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
@@ -37,5 +37,9 @@ import java.util.List;
  */
 @jdk.Exported
 public interface DeprecatedTree extends BlockTagTree {
+    /**
+     * Returns the description explaining why an item is deprecated.
+     * @return the description
+     */
     List<? extends DocTree> getBody();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2014, 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
@@ -37,7 +37,22 @@ import java.util.List;
  */
 @jdk.Exported
 public interface DocCommentTree extends DocTree {
+    /**
+     * Returns the first sentence of a documentation comment.
+     * @return the first sentence of a documentation comment
+     */
     List<? extends DocTree> getFirstSentence();
+
+    /**
+     * Returns the body of a documentation comment,
+     * appearing after the first sentence, and before any block tags.
+     * @return the body of a documentation comment
+     */
     List<? extends DocTree> getBody();
+
+    /**
+     * Returns the block tags for a documentation comment.
+     * @return the block tags of a documentation comment
+     */
     List<? extends DocTree> getBlockTags();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2014, 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
@@ -32,6 +32,9 @@ package com.sun.source.doctree;
  */
 @jdk.Exported
 public interface DocTree {
+    /**
+     * Enumerates all kinds of trees.
+     */
     @jdk.Exported
     enum Kind {
         /**
@@ -227,6 +230,9 @@ public interface DocTree {
          */
         OTHER;
 
+        /**
+         * The name of the tag, if any, associated with this kind of node.
+         */
         public final String tagName;
 
         Kind() {
@@ -239,7 +245,7 @@ public interface DocTree {
     }
 
     /**
-     * Gets the kind of this tree.
+     * Returns the kind of this tree.
      *
      * @return the kind of this tree.
      */
@@ -251,6 +257,9 @@ public interface DocTree {
      *
      * @param <R> result type of this operation.
      * @param <D> type of additional data.
+     * @param visitor the visitor to be called
+     * @param data a parameter value to be passed to the visitor method
+     * @return the value returned from the visitor method
      */
     <R, D> R accept(DocTreeVisitor<R,D> visitor, D data);
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2014, 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
@@ -56,33 +56,238 @@ package com.sun.source.doctree;
  */
 @jdk.Exported
 public interface DocTreeVisitor<R,P> {
+
+    /**
+     * Visits an AttributeTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitAttribute(AttributeTree node, P p);
+
+    /**
+     * Visits an AuthorTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitAuthor(AuthorTree node, P p);
+
+    /**
+     * Visits a CommentTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitComment(CommentTree node, P p);
+
+    /**
+     * Visits a DeprecatedTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitDeprecated(DeprecatedTree node, P p);
+
+    /**
+     * Visits a DocCommentTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitDocComment(DocCommentTree node, P p);
+
+    /**
+     * Visits a DocRootTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitDocRoot(DocRootTree node, P p);
+
+    /**
+     * Visits an EndElementTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitEndElement(EndElementTree node, P p);
+
+    /**
+     * Visits an EntityTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitEntity(EntityTree node, P p);
+
+    /**
+     * Visits an ErroneousTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitErroneous(ErroneousTree node, P p);
+
+    /**
+     * Visits an IdentifierTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitIdentifier(IdentifierTree node, P p);
+
+    /**
+     * Visits an InheritDocTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitInheritDoc(InheritDocTree node, P p);
+
+    /**
+     * Visits a LinkTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitLink(LinkTree node, P p);
+
+    /**
+     * Visits an LiteralTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitLiteral(LiteralTree node, P p);
+
+    /**
+     * Visits a ParamTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitParam(ParamTree node, P p);
+
+    /**
+     * Visits a ReferenceTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitReference(ReferenceTree node, P p);
+
+    /**
+     * Visits a ReturnTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitReturn(ReturnTree node, P p);
+
+    /**
+     * Visits a SeeTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitSee(SeeTree node, P p);
+
+    /**
+     * Visits a SerialTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitSerial(SerialTree node, P p);
+
+    /**
+     * Visits a SerialDataTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitSerialData(SerialDataTree node, P p);
+
+    /**
+     * Visits a SerialFieldTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitSerialField(SerialFieldTree node, P p);
+
+    /**
+     * Visits a SinceTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitSince(SinceTree node, P p);
+
+    /**
+     * Visits a StartElementTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitStartElement(StartElementTree node, P p);
+
+    /**
+     * Visits a TextTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitText(TextTree node, P p);
+
+    /**
+     * Visits a ThrowsTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitThrows(ThrowsTree node, P p);
+
+    /**
+     * Visits an UnknownBlockTagTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitUnknownBlockTag(UnknownBlockTagTree node, P p);
+
+    /**
+     * Visits an UnknownInlineTagTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitUnknownInlineTag(UnknownInlineTagTree node, P p);
+
+    /**
+     * Visits a ValueTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitValue(ValueTree node, P p);
+
+    /**
+     * Visits a VersionTreeTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitVersion(VersionTree node, P p);
+
+    /**
+     * Visits an unknown type of DocTree node.
+     * This can occur if the set of tags evolves and new kinds
+     * of nodes are added to the {@code DocTree} hierarchy.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitOther(DocTree node, P p);
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2014, 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
@@ -37,5 +37,9 @@ import javax.lang.model.element.Name;
  */
 @jdk.Exported
 public interface EndElementTree extends DocTree {
+    /**
+     * Returns the name of this element.
+     * @return the name
+     */
     Name getName();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2014, 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
@@ -32,11 +32,17 @@ import javax.lang.model.element.Name;
  * A tree node for an HTML entity.
  *
  * <p>
- * &amp; name ;
+ * &amp; name ; <br>
+ * &amp; # digits ; <br>
+ * &amp; #X hex-digits ;
  *
  * @since 1.8
  */
 @jdk.Exported
 public interface EntityTree extends DocTree {
+    /**
+     * Returns the name or value of the entity.
+     * @return the name or value of the entity
+     */
     Name getName();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2014, 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
@@ -35,7 +35,7 @@ import javax.tools.JavaFileObject;
 @jdk.Exported
 public interface ErroneousTree extends TextTree {
     /**
-     * Gets a diagnostic object giving details about
+     * Returns a diagnostic object giving details about
      * the reason the body text is in error.
      *
      * @return a diagnostic

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2014, 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
@@ -37,5 +37,9 @@ import javax.lang.model.element.Name;
  */
 @jdk.Exported
 public interface IdentifierTree extends DocTree {
+    /**
+     * Returns the name of the identifier.
+     * @return the name
+     */
     Name getName();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2014, 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
@@ -33,5 +33,9 @@ package com.sun.source.doctree;
  */
 @jdk.Exported
 public interface InlineTagTree extends DocTree {
+    /**
+     * Returns the name of the tag.
+     * @return the name of the tag
+     */
     String getTagName();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2014, 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
@@ -38,6 +38,15 @@ import java.util.List;
  */
 @jdk.Exported
 public interface LinkTree extends InlineTagTree {
+    /**
+     * Returns the reference of a link.
+     * @return the reference
+     */
     ReferenceTree getReference();
+
+    /**
+     * Returns the label, if any, of the link.
+     * @return the label
+     */
     List<? extends DocTree> getLabel();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2014, 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
@@ -36,5 +36,9 @@ package com.sun.source.doctree;
  */
 @jdk.Exported
 public interface LiteralTree extends InlineTagTree {
+    /**
+     * Returns the body of the {@code @code} or {@code @literal} tag.
+     * @return the body of the tag
+     */
     TextTree getBody();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2014, 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
@@ -37,7 +37,21 @@ import java.util.List;
  */
 @jdk.Exported
 public interface ParamTree extends BlockTagTree {
+    /**
+     * Returns true if this is documenting a type parameter.
+     * @return true if this is documenting a type parameter
+     */
     boolean isTypeParameter();
+
+    /**
+     * Returns the name of the parameter.
+     * @return the name of the parameter
+     */
     IdentifierTree getName();
+
+    /**
+     * Returns the description of the parameter.
+     * @return the description
+     */
     List<? extends DocTree> getDescription();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2014, 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,14 +26,20 @@
 package com.sun.source.doctree;
 
 /**
- * A tree node to a reference to a Java language element.
+ * A tree node for a reference to a Java language element.
  *
  * <p>
  * package.class#field
+ * package.class#method(<i>arg-types</i>)
  *
  * @since 1.8
  */
 @jdk.Exported
 public interface ReferenceTree extends DocTree {
+    /**
+     * Returns the signature of the Java language element being referenced,
+     * as found in {@code @see} and similar nodes.
+     * @return the signature.
+     */
     String getSignature();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2014, 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
@@ -37,5 +37,9 @@ import java.util.List;
  */
 @jdk.Exported
 public interface ReturnTree extends BlockTagTree {
+    /**
+     * Returns the description of the return value of a method.
+     * @return the description
+     */
     List<? extends DocTree> getDescription();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2014, 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
@@ -40,5 +40,9 @@ import java.util.List;
  */
 @jdk.Exported
 public interface SeeTree extends BlockTagTree {
+    /**
+     * Returns the reference.
+     * @return the reference
+     */
     List<? extends DocTree> getReference();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2014, 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
@@ -37,5 +37,9 @@ import java.util.List;
  */
 @jdk.Exported
 public interface SerialDataTree extends BlockTagTree {
+    /**
+     * Returns the description of the serial data.
+     * @return the description
+     */
     List<? extends DocTree> getDescription();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2014, 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
@@ -37,7 +37,21 @@ import java.util.List;
  */
 @jdk.Exported
 public interface SerialFieldTree extends BlockTagTree {
+    /**
+     * Returns the name of the serial field.
+     * @return the name of the serial field
+     */
     IdentifierTree getName();
+
+    /**
+     * Returns the type of the serial field.
+     * @return the type of the serial field
+     */
     ReferenceTree getType();
+
+    /**
+     * Returns the description of the serial field.
+     * @return the description of the serial field
+     */
     List<? extends DocTree> getDescription();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2014, 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
@@ -37,5 +37,10 @@ import java.util.List;
  */
 @jdk.Exported
 public interface SerialTree extends BlockTagTree {
+    /**
+     * Returns the description of the field, or the word
+     * "include" or "exclude".
+     * @return the description of the field
+     */
     List<? extends DocTree> getDescription();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2014, 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
@@ -37,5 +37,9 @@ import java.util.List;
  */
 @jdk.Exported
 public interface SinceTree extends BlockTagTree {
+    /**
+     * Returns the text explaining the availability of the item being documented.
+     * @return the text
+     */
     List<? extends DocTree> getBody();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2014, 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
@@ -38,7 +38,22 @@ import javax.lang.model.element.Name;
  */
 @jdk.Exported
 public interface StartElementTree extends DocTree {
+    /**
+     * Returns the name of the element.
+     * @return the name
+     */
     Name getName();
+
+    /**
+     * Returns any attributes defined by this element.
+     * @return the attributes
+     */
     List<? extends DocTree> getAttributes();
+
+    /**
+     * Returns true if this is a self-closing element,
+     * as indicated by a "/" before the closing "&gt;".
+     * @return true if this is a self-closing element
+     */
     boolean isSelfClosing();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2014, 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
@@ -32,5 +32,9 @@ package com.sun.source.doctree;
  */
 @jdk.Exported
 public interface TextTree extends DocTree {
+    /**
+     * Returns the text.
+     * @return the text
+     */
     String getBody();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2014, 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
@@ -40,6 +40,16 @@ import java.util.List;
  */
 @jdk.Exported
 public interface ThrowsTree extends BlockTagTree {
+    /**
+     * Returns a name of the exception being documented.
+     * @return the name of the exception
+     */
     ReferenceTree getExceptionName();
+
+    /**
+     * Returns the description of the reasons why the
+     * exception may be thrown.
+     * @return the description
+     */
     List<? extends DocTree> getDescription();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2014, 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
@@ -37,5 +37,9 @@ import java.util.List;
  */
 @jdk.Exported
 public interface UnknownBlockTagTree extends BlockTagTree {
+    /**
+     * Returns the content of an unrecognized block tag.
+     * @return the content
+     */
     List<? extends DocTree> getContent();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2014, 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
@@ -37,5 +37,9 @@ import java.util.List;
  */
 @jdk.Exported
 public interface UnknownInlineTagTree extends InlineTagTree {
+    /**
+     * Returns the content of an unrecognized inline tag.
+     * @return the content
+     */
     List<? extends DocTree> getContent();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2014, 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
@@ -35,5 +35,9 @@ package com.sun.source.doctree;
  */
 @jdk.Exported
 public interface ValueTree extends InlineTagTree {
+    /**
+     * Returns the reference to the value.
+     * @return the reference
+     */
     ReferenceTree getReference();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2014, 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
@@ -38,5 +38,9 @@ import java.util.List;
  */
 @jdk.Exported
 public interface VersionTree extends BlockTagTree {
+    /**
+     * Returns the body of the tag.
+     * @return the body
+     */
     List<? extends DocTree> getBody();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2008, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2008, 2014, 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
@@ -28,7 +28,7 @@ package com.sun.source.tree;
 import java.util.List;
 
 /**
- * A tree node for an annotated type
+ * A tree node for an annotated type.
  *
  * For example:
  * <pre>
@@ -43,6 +43,15 @@ import java.util.List;
  */
 @jdk.Exported
 public interface AnnotatedTypeTree extends ExpressionTree {
+    /**
+     * Returns the annotations associated with this type expression.
+     * @return the annotations
+     */
     List<? extends AnnotationTree> getAnnotations();
+
+    /**
+     * Returns the underlying type with which the annotations are associated.
+     * @return the underlying type
+     */
     ExpressionTree getUnderlyingType();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -44,6 +44,15 @@ import java.util.List;
  */
 @jdk.Exported
 public interface AnnotationTree extends ExpressionTree {
+    /**
+     * Returns the annotation type.
+     * @return the annotation type
+     */
     Tree getAnnotationType();
+
+    /**
+     * Returns the arguments, if any, for the annotation.
+     * @return the arguments for the annotation type
+     */
     List<? extends ExpressionTree> getArguments();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -41,6 +41,15 @@ package com.sun.source.tree;
  */
 @jdk.Exported
 public interface ArrayAccessTree extends ExpressionTree {
+    /**
+     * Returns the expression for the array being accessed.
+     * @return the array
+     */
     ExpressionTree getExpression();
+
+    /**
+     * Returns the expression for the index.
+     * @return the index
+     */
     ExpressionTree getIndex();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -41,5 +41,9 @@ package com.sun.source.tree;
  */
 @jdk.Exported
 public interface ArrayTypeTree extends Tree {
+    /**
+     * Returns the element type of this array type.
+     * @return the element type
+     */
     Tree getType();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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,7 +26,7 @@
 package com.sun.source.tree;
 
 /**
- * A tree node for an 'assert' statement.
+ * A tree node for an {@code assert} statement.
  *
  * For example:
  * <pre>
@@ -43,6 +43,15 @@ package com.sun.source.tree;
  */
 @jdk.Exported
 public interface AssertTree extends StatementTree {
+    /**
+     * Returns the condition being asserted.
+     * @return the condition
+     */
     ExpressionTree getCondition();
+
+    /**
+     * Returns the detail expression.
+     * @return the detail expression
+     */
     ExpressionTree getDetail();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -41,6 +41,15 @@ package com.sun.source.tree;
  */
 @jdk.Exported
 public interface AssignmentTree extends ExpressionTree {
+    /**
+     * Returns the variable being assigned to.
+     * @return the variable
+     */
     ExpressionTree getVariable();
+
+    /**
+     * Returns the expression being assigned to the variable.
+     * @return the expression
+     */
     ExpressionTree getExpression();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -42,6 +42,15 @@ package com.sun.source.tree;
  */
 @jdk.Exported
 public interface BinaryTree extends ExpressionTree {
+    /**
+     * Returns the left (first) operand of the expression.
+     * @return the left operand
+     */
     ExpressionTree getLeftOperand();
+
+    /**
+     * Returns the right (second) operand of the expression.
+     * @return the right operand
+     */
     ExpressionTree getRightOperand();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -47,6 +47,15 @@ import java.util.List;
  */
 @jdk.Exported
 public interface BlockTree extends StatementTree {
+    /**
+     * Returns true if and only if this is a static initializer block.
+     * @return true if this is a static initializer block
+     */
     boolean isStatic();
+
+    /**
+     * Returns the statements comprising this block.
+     * @return the statements
+     */
     List<? extends StatementTree> getStatements();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -28,7 +28,7 @@ package com.sun.source.tree;
 import javax.lang.model.element.Name;
 
 /**
- * A tree node for a 'break' statement.
+ * A tree node for a {@code break} statement.
  *
  * For example:
  * <pre>
@@ -45,5 +45,9 @@ import javax.lang.model.element.Name;
  */
 @jdk.Exported
 public interface BreakTree extends StatementTree {
+    /**
+     * Returns the label for this {@code break} statement.
+     * @return the label
+     */
     Name getLabel();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -28,7 +28,7 @@ package com.sun.source.tree;
 import java.util.List;
 
 /**
- * A tree node for a 'case' in a 'switch' statement.
+ * A tree node for a {@code case} in a {@code switch} statement.
  *
  * For example:
  * <pre>
@@ -48,8 +48,15 @@ import java.util.List;
 @jdk.Exported
 public interface CaseTree extends Tree {
     /**
-     * @return null if and only if this Case is {@code default:}
+     * Returns the expression for the case, or
+     * {@code null} if this is the default case.
+     * @return the expression for the case, or null
      */
     ExpressionTree getExpression();
+
+    /**
+     * Returns the statements labeled by the case.
+     * @return the statements labeled by the case
+     */
     List<? extends StatementTree> getStatements();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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,7 +26,7 @@
 package com.sun.source.tree;
 
 /**
- * A tree node for a 'catch' block in a 'try' statement.
+ * A tree node for a {@code catch} block in a {@code try} statement.
  *
  * For example:
  * <pre>
@@ -42,6 +42,18 @@ package com.sun.source.tree;
  */
 @jdk.Exported
 public interface CatchTree extends Tree {
+    /**
+     * Returns the catch variable.
+     * A multi-catch variable will have a
+     * {@link UnionTypeTree UnionTypeTree}
+     * as the type of the variable.
+     * @return the catch variable
+     */
     VariableTree getParameter();
+
+    /**
+     * Returns the catch block.
+     * @return the catch block
+     */
     BlockTree getBlock();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -50,10 +50,41 @@ import javax.lang.model.element.Name;
  */
 @jdk.Exported
 public interface ClassTree extends StatementTree {
+    /**
+     * Returns the modifiers, including any annotations,
+     * for this type declaration.
+     * @return the modifiers
+     */
     ModifiersTree getModifiers();
+
+    /**
+     * Returns the simple name of this type declaration.
+     * @return the simple name
+     */
     Name getSimpleName();
+
+    /**
+     * Returns any type parameters of this type declaration.
+     * @return the type parameters
+     */
     List<? extends TypeParameterTree> getTypeParameters();
+
+    /**
+     * Returns the supertype of this type declaration,
+     * or {@code null} if none is provided.
+     * @return the supertype
+     */
     Tree getExtendsClause();
+
+    /**
+     * Returns the interfaces implemented by this type declaration.
+     * @return the interfaces
+     */
     List<? extends Tree> getImplementsClause();
+
+    /**
+     * Returns the members declared in this type declaration.
+     * @return the members
+     */
     List<? extends Tree> getMembers();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -39,21 +39,53 @@ import javax.tools.JavaFileObject;
  */
 @jdk.Exported
 public interface CompilationUnitTree extends Tree {
+    /**
+     * Returns the annotations listed on any package declaration
+     * at the head of this compilation unit, or {@code null} if there
+     * is no package declaration.
+     * @return the package annotations
+     */
     List<? extends AnnotationTree> getPackageAnnotations();
+
+    /**
+     * Returns the name contained in any package declaration
+     * at the head of this compilation unit, or {@code null} if there
+     * is no package declaration.
+     * @return the package name
+     */
     ExpressionTree getPackageName();
 
     /**
-     * Return the PackageTree associated with this compilation unit.
+     * Returns the package tree associated with this compilation unit,
+     * or {@code null} if there is no package declaration.
+     * @return the package tree
      * @since 1.9
      */
     PackageTree getPackage();
+
+    /**
+     * Returns the import declarations appearing in this compilation unit.
+     * @return the import declarations
+     */
     List<? extends ImportTree> getImports();
+
+    /**
+     * Returns the type declarations appearing in this compilation unit.
+     * The list may also include empty statements resulting from
+     * extraneous semicolons.
+     * @return the type declarations
+     */
     List<? extends Tree> getTypeDecls();
+
+    /**
+     * Returns the file object containing the source for this compilation unit.
+     * @return the file object
+     */
     JavaFileObject getSourceFile();
 
     /**
-     * Gets the line map for this compilation unit, if available.
+     * Returns the line map for this compilation unit, if available.
-     * Returns null if the line map is not available.
+     * Returns {@code null} if the line map is not available.
      * @return the line map for this compilation unit
      */
     LineMap getLineMap();

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -42,6 +42,15 @@ package com.sun.source.tree;
  */
 @jdk.Exported
 public interface CompoundAssignmentTree extends ExpressionTree {
+    /**
+     * Returns the variable on the left hand side of the compound assignment.
+     * @return the variable
+     */
     ExpressionTree getVariable();
+
+    /**
+     * Returns the expression on the right hand side of the compound assignment.
+     * @return the expression
+     */
     ExpressionTree getExpression();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -41,7 +41,21 @@ package com.sun.source.tree;
  */
 @jdk.Exported
 public interface ConditionalExpressionTree extends ExpressionTree {
+    /**
+     * Returns the condition.
+     * @return the condition
+     */
     ExpressionTree getCondition();
+
+    /**
+     * Returns the expression to be evaluated if the condition is true.
+     * @return the expression to be evaluated if the condition is true
+     */
     ExpressionTree getTrueExpression();
+
+    /**
+     * Returns the expression to be evaluated if the condition is false.
+     * @return the expression to be evaluated if the condition is false
+     */
     ExpressionTree getFalseExpression();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -28,7 +28,7 @@ package com.sun.source.tree;
 import javax.lang.model.element.Name;
 
 /**
- * A tree node for a 'continue' statement.
+ * A tree node for a {@code continue} statement.
  *
  * For example:
  * <pre>
@@ -44,5 +44,9 @@ import javax.lang.model.element.Name;
  */
 @jdk.Exported
 public interface ContinueTree extends StatementTree {
+    /**
+     * Returns the label for this {@code continue} statement.
+     * @return the label
+     */
     Name getLabel();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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,7 +26,7 @@
 package com.sun.source.tree;
 
 /**
- * A tree node for a 'do' statement.
+ * A tree node for a {@code do} statement.
  *
  * For example:
  * <pre>
@@ -43,6 +43,15 @@ package com.sun.source.tree;
  */
 @jdk.Exported
 public interface DoWhileLoopTree extends StatementTree {
+    /**
+     * Returns the condition of the loop.
+     * @return the condition
+     */
     ExpressionTree getCondition();
+
+    /**
+     * Returns the body of the loop.
+     * @return the body of the loop
+     */
     StatementTree getStatement();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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,7 +26,7 @@
 package com.sun.source.tree;
 
 /**
- * A tree node for an "enhanced" 'for' loop statement.
+ * A tree node for an "enhanced" {@code for} loop statement.
  *
  * For example:
  * <pre>
@@ -42,7 +42,21 @@ package com.sun.source.tree;
  */
 @jdk.Exported
 public interface EnhancedForLoopTree extends StatementTree {
+    /**
+     * Returns the control variable for the loop.
+     * @return the control variable
+     */
     VariableTree getVariable();
+
+    /**
+     * Returns the expression yielding the values for the control variable.
+     * @return the expression
+     */
     ExpressionTree getExpression();
+
+    /**
+     * Returns the body of the loop.
+     * @return the body of the loop
+     */
     StatementTree getStatement();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -36,5 +36,9 @@ import java.util.List;
  */
 @jdk.Exported
 public interface ErroneousTree extends ExpressionTree {
+    /**
+     * Returns any trees that were saved in this node.
+     * @return the trees
+     */
     List<? extends Tree> getErrorTrees();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -41,5 +41,9 @@ package com.sun.source.tree;
  */
 @jdk.Exported
 public interface ExpressionStatementTree extends StatementTree {
+    /**
+     * Returns the expression constituting this statement.
+     * @return the expression
+     */
     ExpressionTree getExpression();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -28,7 +28,7 @@ package com.sun.source.tree;
 import java.util.List;
 
 /**
- * A tree node for a basic 'for' loop statement.
+ * A tree node for a basic {@code for} loop statement.
  *
  * For example:
  * <pre>
@@ -44,8 +44,30 @@ import java.util.List;
  */
 @jdk.Exported
 public interface ForLoopTree extends StatementTree {
+    /**
+     * Returns any initializers of the {@code for} statement.
+     * The result will be an empty list if there are
+     * no initializers
+     * @return the initializers
+     */
     List<? extends StatementTree> getInitializer();
+
+    /**
+     * Returns the condition of the {@code for} statement.
+     * May be {@code null} if there is no condition.
+     * @return the condition
+     */
     ExpressionTree getCondition();
+
+    /**
+     * Returns any update expressions of the {@code for} statement.
+     * @return the update expressions
+     */
     List<? extends ExpressionStatementTree> getUpdate();
+
+    /**
+     * Returns the body of the {@code for} statement.
+     * @return the body
+     */
     StatementTree getStatement();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -43,5 +43,9 @@ import javax.lang.model.element.Name;
  */
 @jdk.Exported
 public interface IdentifierTree extends ExpressionTree {
+    /**
+     * Returns the name of the identifier.
+     * @return the name
+     */
     Name getName();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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,7 +26,7 @@
 package com.sun.source.tree;
 
 /**
- * A tree node for an 'if' statement.
+ * A tree node for an {@code if} statement.
  *
  * For example:
  * <pre>
@@ -47,10 +47,22 @@ package com.sun.source.tree;
  */
 @jdk.Exported
 public interface IfTree extends StatementTree {
-    ExpressionTree getCondition();
-    StatementTree getThenStatement();
     /**
-     * @return null if this if statement has no else branch.
+     * Returns the condition of the if-statement.
+     * @return the condition
+     */
+    ExpressionTree getCondition();
+
+    /**
+     * Returns the statement to be executed if the condition is true
+     * @return the statement to be executed if the condition is true
+     */
+    StatementTree getThenStatement();
+
+    /**
+     * Returns the statement to be executed if the condition is false,
+     * or {@code null} if there is no such statement.
+     * @return the statement to be executed if the condition is false
      */
     StatementTree getElseStatement();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -43,10 +43,19 @@ package com.sun.source.tree;
  */
 @jdk.Exported
 public interface ImportTree extends Tree {
-    boolean isStatic();
     /**
-     * @return a qualified identifier ending in "*" if and only if
+     * Returns true if this is a static import declaration.
-     * this is an import-on-demand.
+     * @return true if this is a static import
+     */
+    boolean isStatic();
+
+    /**
+     * Returns the qualified identifier for the declaration(s)
+     * being imported.
+     * If this is an import-on-demand declaration, the
+     * qualified identifier will end in "*".
+     * @return a qualified identifier, ending in "*" if and only if
+     * this is an import-on-demand
      */
     Tree getQualifiedIdentifier();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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,7 +26,7 @@
 package com.sun.source.tree;
 
 /**
- * A tree node for an 'instanceof' expression.
+ * A tree node for an {@code instanceof} expression.
  *
  * For example:
  * <pre>
@@ -41,6 +41,15 @@ package com.sun.source.tree;
  */
 @jdk.Exported
 public interface InstanceOfTree extends ExpressionTree {
+    /**
+     * Returns the expression to be tested.
+     * @return the expression
+     */
     ExpressionTree getExpression();
+
+    /**
+     * Returns the type for which to check.
+     * @return the type
+     */
     Tree getType();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2014, 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
@@ -36,5 +36,9 @@ import java.util.List;
  */
 @jdk.Exported
 public interface IntersectionTypeTree extends Tree {
+    /**
+     * Returns the bounds of the type.
+     * @return the bounds
+     */
     List<? extends Tree> getBounds();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -43,6 +43,15 @@ import javax.lang.model.element.Name;
  */
 @jdk.Exported
 public interface LabeledStatementTree extends StatementTree {
+    /**
+     * Returns the label.
+     * @return the label
+     */
     Name getLabel();
+
+    /**
+     * Returns the statement that is labeled.
+     * @return the statement
+     */
     StatementTree getStatement();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2014, 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
@@ -41,8 +41,11 @@ import java.util.List;
 public interface LambdaExpressionTree extends ExpressionTree {
 
     /**
-     * Lambda expressions come in two forms: (i) expression lambdas, whose body
+     * Lambda expressions come in two forms:
-     * is an expression, and (ii) statement lambdas, whose body is a block
+     * <ul compact>
+     * <li> expression lambdas, whose body is an expression, and
+     * <li> statement lambdas, whose body is a block
+     * </ul>
      */
     @jdk.Exported
     public enum BodyKind {
@@ -52,7 +55,21 @@ public interface LambdaExpressionTree extends ExpressionTree {
         STATEMENT
     }
 
+    /**
+     * Returns the parameters of this lambda expression.
+     * @return the parameters
+     */
     List<? extends VariableTree> getParameters();
+
+    /**
+     * Returns the body of the lambda expression.
+     * @return the body
+     */
     Tree getBody();
+
+    /**
+     * Returns the kind of the body of the lambda expression.
+     * @return the kind of the body
+     */
     BodyKind getBodyKind();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2006, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2006, 2014, 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
@@ -34,7 +34,7 @@ package com.sun.source.tree;
 @jdk.Exported
 public interface LineMap {
     /**
-     * Find the start position of a line.
+     * Finds the start position of a line.
      *
      * @param line line number (beginning at 1)
      * @return     position of first character in line
@@ -45,7 +45,7 @@ public interface LineMap {
     long getStartPosition(long line);
 
     /**
-     * Find the position corresponding to a (line,column).
+     * Finds the position corresponding to a (line,column).
      *
      * @param   line    line number (beginning at 1)
      * @param   column  tab-expanded column number (beginning 1)
@@ -58,7 +58,7 @@ public interface LineMap {
     long getPosition(long line, long column);
 
     /**
-     * Find the line containing a position; a line termination
+     * Finds the line containing a position; a line termination
      * character is on the line it terminates.
      *
      * @param   pos  character offset of the position
@@ -67,7 +67,7 @@ public interface LineMap {
     long getLineNumber(long pos);
 
     /**
-     * Find the column for a character position.
+     * Finds the column for a character position.
      * Tab characters preceding the position on the same line
      * will be expanded when calculating the column number.
      *

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -42,5 +42,10 @@ package com.sun.source.tree;
  */
 @jdk.Exported
 public interface LiteralTree extends ExpressionTree {
+    /**
+     * Returns the value of the literal expression.
+     * The value will be a boxed primitive value, a String, or {@code null}.
+     * @return the value
+     */
     Object getValue();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2014, 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
@@ -48,13 +48,33 @@ public interface MemberReferenceTree extends ExpressionTree {
      */
     @jdk.Exported
     public enum ReferenceMode {
-        /** enum constant for method references */
+        /** enum constant for method references. */
         INVOKE,
-        /** enum constant for constructor references */
+        /** enum constant for constructor references. */
         NEW
     }
+
+    /**
+     * Returns the mode of the reference.
+     * @return the mode
+     */
     ReferenceMode getMode();
+
+    /**
+     * Returns the qualifier expression for the reference.
+     * @return the qualifier expression
+     */
     ExpressionTree getQualifierExpression();
+
+    /**
+     * Returns the name of the reference.
+     * @return the name
+     */
     Name getName();
+
+    /**
+     * Returns the type arguments for the reference.
+     * @return the type arguments
+     */
     List<? extends ExpressionTree> getTypeArguments();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -43,6 +43,15 @@ import javax.lang.model.element.Name;
  */
 @jdk.Exported
 public interface MemberSelectTree extends ExpressionTree {
+    /**
+     * Returns the expression for which a member is to be selected.
+     * @return the expression.
+     */
     ExpressionTree getExpression();
+
+    /**
+     * Returns the name of the member to be selected.
+     * @return the member
+     */
     Name getIdentifier();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -45,7 +45,21 @@ import java.util.List;
  */
 @jdk.Exported
 public interface MethodInvocationTree extends ExpressionTree {
+    /**
+     * Returns the type arguments for this method invocation.
+     * @return the type arguments
+     */
     List<? extends Tree> getTypeArguments();
+
+    /**
+     * Returns the expression identifying the method to be invoked.
+     * @return the method selection expression
+     */
     ExpressionTree getMethodSelect();
+
+    /**
+     * Returns the arguments for the method invocation.
+     * @return the arguments
+     */
     List<? extends ExpressionTree> getArguments();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -48,21 +48,63 @@ import javax.lang.model.element.Name;
  */
 @jdk.Exported
 public interface MethodTree extends Tree {
+    /**
+     * Returns the modifiers, including any annotations for the method being declared.
+     * @return the modifiers
+     */
     ModifiersTree getModifiers();
+
+    /**
+     * Returns the name of the method being declared.
+     * @return the name
+     */
     Name getName();
+
+    /**
+     * Returns the return type of the method being declared.
+     * Returns {@code null} for a constructor.
+     * @return the return type
+     */
     Tree getReturnType();
+
+    /**
+     * Returns the type parameters of the method being declared.
+     * @return the type parameters
+     */
     List<? extends TypeParameterTree> getTypeParameters();
+
+    /**
+     * Returns the parameters of the method being declared.
+     * @return the parameters
+     */
     List<? extends VariableTree> getParameters();
 
     /**
-     * Return an explicit receiver parameter ("this" parameter).
+     * Return an explicit receiver parameter ("this" parameter),
+     * or {@code null} if none.
      *
      * @return an explicit receiver parameter ("this" parameter)
      * @since 1.8
      */
     VariableTree getReceiverParameter();
 
+    /**
+     * Returns the exceptions listed as being thrown by this method.
+     * @return the exceptions
+     */
     List<? extends ExpressionTree> getThrows();
+
+    /**
+     * Returns the method body, or {@code null} if this is an abstract or native method.
+     * @return the method body
+     */
     BlockTree getBody();
+
+    /**
+     * Returns the default value, if this is an element within
+     * an annotation type declaration.
+     * Returns {@code null} otherwise.
+     * @return the default value
+     */
     Tree getDefaultValue(); // for annotation types
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -47,6 +47,15 @@ import javax.lang.model.element.Modifier;
  */
 @jdk.Exported
 public interface ModifiersTree extends Tree {
+    /**
+     * Returns the flags in this modifiers tree.
+     * @return the flags
+     */
     Set<Modifier> getFlags();
+
+    /**
+     * Returns the annotations in this modifiers tree.
+     * @return the annotations
+     */
     List<? extends AnnotationTree> getAnnotations();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -45,9 +45,37 @@ import java.util.List;
  */
 @jdk.Exported
 public interface NewArrayTree extends ExpressionTree {
+    /**
+     * Returns the base type of the expression.
+     * May be {@code null} for an array initializer expression.
+     * @return the base type
+     */
     Tree getType();
+
+    /**
+     * Returns the dimension expressions for the type.
+     *
+     * @return the dimension expressions
+     */
     List<? extends ExpressionTree> getDimensions();
+
+    /**
+     * Returns the initializer expressions.
+     *
+     * @return the initializer expressions
+     */
     List<? extends ExpressionTree> getInitializers();
+
+    /**
+     * Returns the annotations on the base type.
+     * @return the annotations
+     */
     List<? extends AnnotationTree> getAnnotations();
+
+    /**
+     * Returns the annotations on each of the dimension
+     * expressions.
+     * @return the annotations on the dimensions expressions
+     */
     List<? extends List<? extends AnnotationTree>> getDimAnnotations();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -50,9 +50,34 @@ import java.util.List;
  */
 @jdk.Exported
 public interface NewClassTree extends ExpressionTree {
+    /**
+     * Returns the enclosing expression, or {@code null} if none.
+     * @return the enclosing expression
+     */
     ExpressionTree getEnclosingExpression();
+
+    /**
+     * Returns the type arguments for the object being created.
+     * @return the type arguments
+     */
     List<? extends Tree> getTypeArguments();
+
+    /**
+     * Returns the name of the class being instantiated.
+     * @return the name
+     */
     ExpressionTree getIdentifier();
+
+    /**
+     * Returns the arguments for the constructor to be invoked.
+     * @return the arguments
+     */
     List<? extends ExpressionTree> getArguments();
+
+    /**
+     * Returns the class body if an anonymous class is being
+     * instantiated, and {@code null} otherwise.
+     * @return the class body
+     */
     ClassTree getClassBody();
 }

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

@@ -37,6 +37,15 @@ import java.util.List;
  */
 @jdk.Exported
 public interface PackageTree extends Tree {
+    /**
+     * Returns the annotations associated with this package declaration.
+     * @return the annotations
+     */
     List<? extends AnnotationTree> getAnnotations();
+
+    /**
+     * Returns the name of the package being declared.
+     * @return the name
+     */
     ExpressionTree getPackageName();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -43,6 +43,15 @@ import java.util.List;
  */
 @jdk.Exported
 public interface ParameterizedTypeTree extends Tree {
+    /**
+     * Returns the base type.
+     * @return the base type
+     */
     Tree getType();
+
+    /**
+     * Returns the type arguments.
+     * @return the type arguments
+     */
     List<? extends Tree> getTypeArguments();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -42,5 +42,9 @@ package com.sun.source.tree;
  */
 @jdk.Exported
 public interface ParenthesizedTree extends ExpressionTree {
+    /**
+     * Returns the expression within the parentheses.
+     * @return the expression
+     */
     ExpressionTree getExpression();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -43,5 +43,9 @@ import javax.lang.model.type.TypeKind;
  */
 @jdk.Exported
 public interface PrimitiveTypeTree extends Tree {
+    /**
+     * Returns the kind of this primitive type.
+     * @return the kind of the type
+     */
     TypeKind getPrimitiveTypeKind();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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,7 +26,7 @@
 package com.sun.source.tree;
 
 /**
- * A tree node for a 'return' statement.
+ * A tree node for a {@code return} statement.
  *
  * For example:
  * <pre>
@@ -42,5 +42,9 @@ package com.sun.source.tree;
  */
 @jdk.Exported
 public interface ReturnTree extends StatementTree {
+    /**
+     * Returns the expression to be returned.
+     * @return the expression
+     */
     ExpressionTree getExpression();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2006, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2006, 2014, 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
@@ -52,21 +52,25 @@ import javax.lang.model.element.TypeElement;
 public interface Scope {
     /**
      * Returns the enclosing scope.
+     * @return the enclosing scope
      */
     public Scope getEnclosingScope();
 
     /**
-     * Returns the innermost type element containing the position of this scope
+     * Returns the innermost type element containing the position of this scope.
+     * @return the innermost enclosing type element
      */
     public TypeElement getEnclosingClass();
 
     /**
      * Returns the innermost executable element containing the position of this scope.
+     * @return the innermost enclosing method declaration
      */
     public ExecutableElement getEnclosingMethod();
 
     /**
      * Returns the elements directly contained in this scope.
+     * @return the elements contained in this scope
      */
     public Iterable<? extends Element> getLocalElements();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -28,7 +28,7 @@ package com.sun.source.tree;
 import java.util.List;
 
 /**
- * A tree node for a 'switch' statement.
+ * A tree node for a {@code switch} statement.
  *
  * For example:
  * <pre>
@@ -45,6 +45,15 @@ import java.util.List;
  */
 @jdk.Exported
 public interface SwitchTree extends StatementTree {
+    /**
+     * Returns the expression for the {@code switch} statement.
+     * @return the expression
+     */
     ExpressionTree getExpression();
+
+    /**
+     * Returns the cases for the {@code switch} statement.
+     * @return the cases
+     */
     List<? extends CaseTree> getCases();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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,7 +26,7 @@
 package com.sun.source.tree;
 
 /**
- * A tree node for a 'synchronized' statement.
+ * A tree node for a {@code synchronized} statement.
  *
  * For example:
  * <pre>
@@ -42,6 +42,15 @@ package com.sun.source.tree;
  */
 @jdk.Exported
 public interface SynchronizedTree extends StatementTree {
+    /**
+     * Returns the expression on which to synchronize.
+     * @return the expression
+     */
     ExpressionTree getExpression();
+
+    /**
+     * Returns the block of the {@code synchronized} statement.
+     * @return the block
+     */
     BlockTree getBlock();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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,7 +26,7 @@
 package com.sun.source.tree;
 
 /**
- * A tree node for a 'throw' statement.
+ * A tree node for a {@code throw} statement.
  *
  * For example:
  * <pre>
@@ -41,5 +41,9 @@ package com.sun.source.tree;
  */
 @jdk.Exported
 public interface ThrowTree extends StatementTree {
+    /**
+     * Returns the expression to be thrown.
+     * @return the expression
+     */
     ExpressionTree getExpression();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -47,7 +47,10 @@ public interface Tree {
      */
     @jdk.Exported
     public enum Kind {
-
+        /**
+         * Used for instances of {@link AnnotatedTypeTree}
+         * representing annotated types.
+         */
         ANNOTATED_TYPE(AnnotatedTypeTree.class),
 
         /**
@@ -613,6 +616,10 @@ public interface Tree {
             associatedInterface = intf;
         }
 
+        /**
+         * Returns the associated interface type that uses this kind.
+         * @return the associated interface
+         */
         public Class<? extends Tree> asInterface() {
             return associatedInterface;
         }
@@ -621,7 +628,7 @@ public interface Tree {
     }
 
     /**
-     * Gets the kind of this tree.
+     * Returns the kind of this tree.
      *
      * @return the kind of this tree.
      */
@@ -633,6 +640,9 @@ public interface Tree {
      *
      * @param <R> result type of this operation.
      * @param <D> type of additional data.
+     * @param visitor the visitor to be called
+     * @param data a value to be passed to the visitor
+     * @return the result returned from calling the visitor
      */
     <R,D> R accept(TreeVisitor<R,D> visitor, D data);
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -58,58 +58,437 @@ package com.sun.source.tree;
  */
 @jdk.Exported
 public interface TreeVisitor<R,P> {
+    /**
+     * Visits an AnnotatedTypeTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitAnnotatedType(AnnotatedTypeTree node, P p);
+
+    /**
+     * Visits an AnnotatedTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitAnnotation(AnnotationTree node, P p);
+
+    /**
+     * Visits a MethodInvocationTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitMethodInvocation(MethodInvocationTree node, P p);
+
+    /**
+     * Visits an AssertTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitAssert(AssertTree node, P p);
+
+    /**
+     * Visits an AssignmentTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitAssignment(AssignmentTree node, P p);
+
+    /**
+     * Visits a CompoundAssignmentTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitCompoundAssignment(CompoundAssignmentTree node, P p);
+
+    /**
+     * Visits a BinaryTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitBinary(BinaryTree node, P p);
+
+    /**
+     * Visits a BlockTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitBlock(BlockTree node, P p);
+
+    /**
+     * Visits a BreakTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitBreak(BreakTree node, P p);
+
+    /**
+     * Visits a CaseTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitCase(CaseTree node, P p);
+
+    /**
+     * Visits a CatchTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitCatch(CatchTree node, P p);
+
+    /**
+     * Visits a ClassTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitClass(ClassTree node, P p);
+
+    /**
+     * Visits a ConditionalExpressionTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitConditionalExpression(ConditionalExpressionTree node, P p);
+
+    /**
+     * Visits a ContinueTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitContinue(ContinueTree node, P p);
+
+    /**
+     * Visits a DoWhileTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitDoWhileLoop(DoWhileLoopTree node, P p);
+
+    /**
+     * Visits an ErroneousTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitErroneous(ErroneousTree node, P p);
+
+    /**
+     * Visits an ExpressionStatementTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitExpressionStatement(ExpressionStatementTree node, P p);
+
+    /**
+     * Visits an EnhancedForLoopTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitEnhancedForLoop(EnhancedForLoopTree node, P p);
+
+    /**
+     * Visits a ForLoopTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitForLoop(ForLoopTree node, P p);
+
+    /**
+     * Visits an IdentifierTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitIdentifier(IdentifierTree node, P p);
+
+    /**
+     * Visits an IfTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitIf(IfTree node, P p);
+
+    /**
+     * Visits an ImportTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitImport(ImportTree node, P p);
+
+    /**
+     * Visits an ArrayAccessTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitArrayAccess(ArrayAccessTree node, P p);
+
+    /**
+     * Visits a LabeledStatementTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitLabeledStatement(LabeledStatementTree node, P p);
+
+    /**
+     * Visits a LiteralTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitLiteral(LiteralTree node, P p);
+
+    /**
+     * Visits a MethodTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitMethod(MethodTree node, P p);
+
+    /**
+     * Visits a ModifiersTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitModifiers(ModifiersTree node, P p);
+
+    /**
+     * Visits a NewArrayTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitNewArray(NewArrayTree node, P p);
+
+    /**
+     * Visits a NewClassTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitNewClass(NewClassTree node, P p);
+
+    /**
+     * Visits a LambdaExpressionTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitLambdaExpression(LambdaExpressionTree node, P p);
+
+    /**
+     * Visits a PackageTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitPackage(PackageTree node, P p);
+
+    /**
+     * Visits a ParenthesizedTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitParenthesized(ParenthesizedTree node, P p);
+
+    /**
+     * Visits a ReturnTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitReturn(ReturnTree node, P p);
+
+    /**
+     * Visits a MemberSelectTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitMemberSelect(MemberSelectTree node, P p);
+
+    /**
+     * Visits a MemberReferenceTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitMemberReference(MemberReferenceTree node, P p);
+
+    /**
+     * Visits an EmptyStatementTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitEmptyStatement(EmptyStatementTree node, P p);
+
+    /**
+     * Visits a SwitchTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitSwitch(SwitchTree node, P p);
+
+    /**
+     * Visits a SynchronizedTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitSynchronized(SynchronizedTree node, P p);
+
+    /**
+     * Visits a ThrowTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitThrow(ThrowTree node, P p);
+
+    /**
+     * Visits a CompilationUnitTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitCompilationUnit(CompilationUnitTree node, P p);
+
+    /**
+     * Visits a TryTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitTry(TryTree node, P p);
+
+    /**
+     * Visits a ParameterizedTypeTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitParameterizedType(ParameterizedTypeTree node, P p);
+
+    /**
+     * Visits a UnionTypeTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitUnionType(UnionTypeTree node, P p);
+
+    /**
+     * Visits an IntersectionTypeTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitIntersectionType(IntersectionTypeTree node, P p);
+
+    /**
+     * Visits an ArrayTypeTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitArrayType(ArrayTypeTree node, P p);
+
+    /**
+     * Visits a TypeCastTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitTypeCast(TypeCastTree node, P p);
+
+    /**
+     * Visits a PrimitiveTypeTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitPrimitiveType(PrimitiveTypeTree node, P p);
+
+    /**
+     * Visits a TypeParameterTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitTypeParameter(TypeParameterTree node, P p);
+
+    /**
+     * Visits an InstanceOfTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitInstanceOf(InstanceOfTree node, P p);
+
+    /**
+     * Visits a UnaryTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitUnary(UnaryTree node, P p);
+
+    /**
+     * Visits a VariableTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitVariable(VariableTree node, P p);
+
+    /**
+     * Visits a WhileLoopTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitWhileLoop(WhileLoopTree node, P p);
+
+    /**
+     * Visits a WildcardTypeTree node.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitWildcard(WildcardTree node, P p);
+
+    /**
+     * Visits an unknown type of Tree node.
+     * This can occur if the language evolves and new kinds
+     * of nodes are added to the {@code Tree} hierarchy.
+     * @param node the node being visited
+     * @param p a parameter value
+     * @return a result value
+     */
     R visitOther(Tree node, P p);
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -28,7 +28,7 @@ package com.sun.source.tree;
 import java.util.List;
 
 /**
- * A tree node for a 'try' statement.
+ * A tree node for a {@code try} statement.
  *
  * For example:
  * <pre>
@@ -47,8 +47,33 @@ import java.util.List;
  */
 @jdk.Exported
 public interface TryTree extends StatementTree {
+    /**
+     * Returns the block of the {@code try} statement.
+     * @return the block
+     */
     BlockTree getBlock();
+
+    /**
+     * Returns any catch blocks provided in the {@code try} statement.
+     * The result will be an empty list if there are no
+     * catch blocks.
+     * @return the catch blocks
+     */
     List<? extends CatchTree> getCatches();
+
+    /**
+     * Returns the finally block provided in the {@code try} statement,
+     * or {@code null} if there is none.
+     * @return the finally block
+     */
     BlockTree getFinallyBlock();
+
+
+    /**
+     * Returns any resource declarations provided in the {@code try} statement.
+     * The result will be an empty list if there are no
+     * resource declarations.
+     * @return the resource declarations
+     */
     List<? extends Tree> getResources();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -41,6 +41,15 @@ package com.sun.source.tree;
  */
 @jdk.Exported
 public interface TypeCastTree extends ExpressionTree {
+    /**
+     * Returns the target type of the cast.
+     * @return the cast
+     */
     Tree getType();
+
+    /**
+     * Returns the expression being cast.
+     * @return the expression
+     */
     ExpressionTree getExpression();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -48,11 +48,20 @@ import javax.lang.model.element.Name;
  */
 @jdk.Exported
 public interface TypeParameterTree extends Tree {
+    /**
+     * Returns the name of the type parameter.
+     * @return the name
+     */
     Name getName();
+
+    /**
+     * Returns the bounds of the type parameter.
+     * @return the bounds
+     */
     List<? extends Tree> getBounds();
 
     /**
-     * Return annotations on the type parameter declaration.
+     * Returns annotations on the type parameter declaration.
      *
      * Annotations need Target meta-annotations of
      * {@link java.lang.annotation.ElementType#TYPE_PARAMETER} or

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -44,5 +44,9 @@ package com.sun.source.tree;
  */
 @jdk.Exported
 public interface UnaryTree extends ExpressionTree {
+    /**
+     * Returns the expression that is the operand of the unary operator.
+     * @return the expression
+     */
     ExpressionTree getExpression();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2014, 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
@@ -28,7 +28,8 @@ package com.sun.source.tree;
 import java.util.List;
 
 /**
- * A tree node for a union type expression in a multicatch var declaration.
+ * A tree node for a union type expression in a multicatch
+ * variable declaration.
  *
  * @author Maurizio Cimadamore
  *
@@ -36,5 +37,9 @@ import java.util.List;
  */
 @jdk.Exported
 public interface UnionTypeTree extends Tree {
+    /**
+     * Returns the alternative type expressions.
+     * @return the alternative type expressions
+     */
     List<? extends Tree> getTypeAlternatives();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -44,9 +44,35 @@ import javax.lang.model.element.Name;
  */
 @jdk.Exported
 public interface VariableTree extends StatementTree {
+    /**
+     * Returns the modifiers, including any annotations, on the declaration.
+     * @return the modifiers
+     */
     ModifiersTree getModifiers();
+
+    /**
+     * Returns the name of the variable being declared.
+     * @return the name
+     */
     Name getName();
+
+    /**
+     * Returns the qualified identifier for the name being "declared".
+     * This is only used in certain cases for the receiver of a
+     * method declaration. Returns {@code null} in all other cases.
+     * @return the qualified identifier of a receiver declaration
+     */
     ExpressionTree getNameExpression();
+
+    /**
+     * Returns the type of the variable being declared.
+     * @return the type
+     */
     Tree getType();
+
+    /**
+     * Returns the initializer for the variable, or {@code null} if none.
+     * @return the initializer
+     */
     ExpressionTree getInitializer();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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,7 +26,7 @@
 package com.sun.source.tree;
 
 /**
- * A tree node for a 'while' loop statement.
+ * A tree node for a {@code while} loop statement.
  *
  * For example:
  * <pre>
@@ -43,6 +43,15 @@ package com.sun.source.tree;
  */
 @jdk.Exported
 public interface WhileLoopTree extends StatementTree {
+    /**
+     * Returns the condition of the loop.
+     * @return the condition
+     */
     ExpressionTree getCondition();
+
+    /**
+     * Returns the body of the loop.
+     * @return the body of the loop
+     */
     StatementTree getStatement();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -46,5 +46,9 @@ package com.sun.source.tree;
  */
 @jdk.Exported
 public interface WildcardTree extends Tree {
+    /**
+     * Returns the bound of the wildcard.
+     * @return the bound
+     */
     Tree getBound();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2013, 2014, 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
@@ -40,7 +40,7 @@ import com.sun.source.tree.CompilationUnitTree;
 public interface DocSourcePositions extends SourcePositions {
 
     /**
-     * Gets the starting position of the tree within the comment within the file.  If tree is not found within
+     * Returns the starting position of the tree within the comment within the file.  If tree is not found within
      * file, or if the starting position is not available,
      * return {@link javax.tools.Diagnostic#NOPOS}.
      * The given tree should be under the given comment tree, and the given documentation
@@ -64,7 +64,7 @@ public interface DocSourcePositions extends SourcePositions {
     long getStartPosition(CompilationUnitTree file, DocCommentTree comment, DocTree tree);
 
     /**
-     * Gets the ending position of the tree within the comment within the file.  If tree is not found within
+     * Returns the ending position of the tree within the comment within the file.  If tree is not found within
      * file, or if the ending position is not available,
      * return {@link javax.tools.Diagnostic#NOPOS}.
      * The given tree should be under the given comment tree, and the given documentation

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2006, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2006, 2014, 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
@@ -38,16 +38,23 @@ import java.util.Iterator;
 @jdk.Exported
 public class DocTreePath implements Iterable<DocTree> {
     /**
-     * Gets a documentation tree path for a tree node within a compilation unit.
+     * Returns a documentation tree path for a tree node within a compilation unit,
-     * @return null if the node is not found
+     * or {@code null} if the node is not found.
+     * @param treePath the path for the node with which the doc comment is associated
+     * @param doc the doc comment associated with the node
+     * @param target a node within the doc comment
+     * @return a path identifying the target within the tree
      */
     public static DocTreePath getPath(TreePath treePath, DocCommentTree doc, DocTree target) {
         return getPath(new DocTreePath(treePath, doc), target);
     }
 
     /**
-     * Gets a documentation tree path for a tree node within a subtree identified by a DocTreePath object.
+     * Returns a documentation tree path for a tree node within a subtree
-     * @return null if the node is not found
+     * identified by a DocTreePath object, or {@code null} if the node is not found.
+     * @param path a path identifying a node within a doc comment tree
+     * @param target a node to be located within the given node
+     * @return a path identifying the target node
      */
     public static DocTreePath getPath(DocTreePath path, DocTree target) {
         path.getClass();
@@ -100,6 +107,8 @@ public class DocTreePath implements Iterable<DocTree> {
 
     /**
      * Creates a DocTreePath for a child node.
+     * @param p the parent node
+     * @param t the child node
      */
     public DocTreePath(DocTreePath p, DocTree t) {
         if (t.getKind() == DocTree.Kind.DOC_COMMENT) {
@@ -113,31 +122,31 @@ public class DocTreePath implements Iterable<DocTree> {
     }
 
     /**
-     * Get the TreePath associated with this path.
+     * Returns the TreePath associated with this path.
-     * @return TreePath for this DocTreePath
+     * @return the TreePath for this DocTreePath
      */
     public TreePath getTreePath() {
         return treePath;
     }
 
     /**
-     * Get the DocCommentTree associated with this path.
+     * Returns the DocCommentTree associated with this path.
-     * @return DocCommentTree for this DocTreePath
+     * @return the DocCommentTree for this DocTreePath
      */
     public DocCommentTree getDocComment() {
         return docComment;
     }
 
     /**
-     * Get the leaf node for this path.
+     * Returns the leaf node for this path.
-     * @return DocTree for this DocTreePath
+     * @return the DocTree for this DocTreePath
      */
     public DocTree getLeaf() {
         return leaf;
     }
 
     /**
-     * Get the path for the enclosing node, or null if there is no enclosing node.
+     * Returns the path for the enclosing node, or {@code null} if there is no enclosing node.
      * @return DocTreePath of parent
      */
     public DocTreePath getParentPath() {

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2006, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2006, 2014, 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
@@ -39,7 +39,10 @@ import com.sun.source.doctree.DocTree;
 @jdk.Exported
 public class DocTreePathScanner<R, P> extends DocTreeScanner<R, P> {
     /**
-     * Scan a tree from a position identified by a TreePath.
+     * Scans a tree from a position identified by a tree path.
+     * @param path the path
+     * @param p a value to be passed to visitor methods
+     * @return the result returned from the main visitor method
      */
     public R scan(DocTreePath path, P p) {
         this.path = path;
@@ -51,8 +54,11 @@ public class DocTreePathScanner<R, P> extends DocTreeScanner<R, P> {
     }
 
     /**
-     * Scan a single node.
+     * Scans a single node.
      * The current path is updated for the duration of the scan.
+     * @param tree the tree to be scanned
+     * @param p a value to be passed to visitor methods
+     * @return the result returned from the main visitor method
      */
     @Override
     public R scan(DocTree tree, P p) {
@@ -69,8 +75,9 @@ public class DocTreePathScanner<R, P> extends DocTreeScanner<R, P> {
     }
 
     /**
-     * Get the current path for the node, as built up by the currently
+     * Returns the current path for the node, as built up by the currently
      * active set of scan calls.
+     * @return the current path
      */
     public DocTreePath getCurrentPath() {
         return path;

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2014, 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
@@ -38,7 +38,7 @@ import com.sun.source.doctree.*;
  * <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 no children, the result will be {@code 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.
@@ -71,7 +71,10 @@ import com.sun.source.doctree.*;
 public class DocTreeScanner<R,P> implements DocTreeVisitor<R,P> {
 
     /**
-     * Scan a single node.
+     * Scans a single node.
+     * @param node the node to be scanned
+     * @param p a parameter value passed to the visit method
+     * @return the result value from the visit method
      */
     public R scan(DocTree node, P p) {
         return (node == null) ? null : node.accept(this, p);
@@ -82,7 +85,11 @@ public class DocTreeScanner<R,P> implements DocTreeVisitor<R,P> {
     }
 
     /**
-     * Scan a list of nodes.
+     * Scans a sequence of nodes.
+     * @param nodes the nodes to be scanned
+     * @param p a parameter value to be passed to the visit method for each node
+     * @return the combined return value from the visit methods.
+     *      The values are combined using the {@link #reduce reduce} method.
      */
     public R scan(Iterable<? extends DocTree> nodes, P p) {
         R r = null;
@@ -104,6 +111,9 @@ public class DocTreeScanner<R,P> implements DocTreeVisitor<R,P> {
      * 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.
+     * @param r1 the first of the values to be combined
+     * @param r2 the second of the values to be combined
+     * @return the result of combining the two parameters
      */
     public R reduce(R r1, R r2) {
         return r1;
@@ -114,26 +124,61 @@ public class DocTreeScanner<R,P> implements DocTreeVisitor<R,P> {
  * Visitor methods
  ****************************************************************************/
 
+    /**
+     * {@inheritDoc} This implementation returns {@code null}.
+     *
+     * @param node  {@inheritDoc}
+     * @param p  {@inheritDoc}
+     * @return the result of scanning
+     */
     @Override
     public R visitAttribute(AttributeTree node, P p) {
         return null;
     }
 
+    /**
+     * {@inheritDoc} This implementation scans the children in left to right order.
+     *
+     * @param node  {@inheritDoc}
+     * @param p  {@inheritDoc}
+     * @return the result of scanning
+     */
     @Override
     public R visitAuthor(AuthorTree node, P p) {
         return scan(node.getName(), p);
     }
 
+    /**
+     * {@inheritDoc} This implementation returns {@code null}.
+     *
+     * @param node  {@inheritDoc}
+     * @param p  {@inheritDoc}
+     * @return the result of scanning
+     */
     @Override
     public R visitComment(CommentTree node, P p) {
         return null;
     }
 
+    /**
+     * {@inheritDoc} This implementation scans the children in left to right order.
+     *
+     * @param node  {@inheritDoc}
+     * @param p  {@inheritDoc}
+     * @return the result of scanning
+     */
     @Override
     public R visitDeprecated(DeprecatedTree node, P p) {
         return scan(node.getBody(), p);
     }
 
+    /**
+     * {@inheritDoc} This implementation scans the children in left to right order.
+     *
+     * @param node  {@inheritDoc}
+     * @param p  {@inheritDoc}
+     * @return the result of scanning
+     */
     @Override
     public R visitDocComment(DocCommentTree node, P p) {
         R r = scan(node.getFirstSentence(), p);
@@ -142,36 +187,85 @@ public class DocTreeScanner<R,P> implements DocTreeVisitor<R,P> {
         return r;
     }
 
+    /**
+     * {@inheritDoc} This implementation returns {@code null}.
+     *
+     * @param node  {@inheritDoc}
+     * @param p  {@inheritDoc}
+     * @return the result of scanning
+     */
     @Override
     public R visitDocRoot(DocRootTree node, P p) {
         return null;
     }
 
+    /**
+     * {@inheritDoc} This implementation returns {@code null}.
+     *
+     * @param node  {@inheritDoc}
+     * @param p  {@inheritDoc}
+     * @return the result of scanning
+     */
     @Override
     public R visitEndElement(EndElementTree node, P p) {
         return null;
     }
 
+    /**
+     * {@inheritDoc} This implementation returns {@code null}.
+     *
+     * @param node  {@inheritDoc}
+     * @param p  {@inheritDoc}
+     * @return the result of scanning
+     */
     @Override
     public R visitEntity(EntityTree node, P p) {
         return null;
     }
 
+    /**
+     * {@inheritDoc} This implementation returns {@code null}.
+     *
+     * @param node  {@inheritDoc}
+     * @param p  {@inheritDoc}
+     * @return the result of scanning
+     */
     @Override
     public R visitErroneous(ErroneousTree node, P p) {
         return null;
     }
 
+    /**
+     * {@inheritDoc} This implementation returns {@code null}.
+     *
+     * @param node  {@inheritDoc}
+     * @param p  {@inheritDoc}
+     * @return the result of scanning
+     */
     @Override
     public R visitIdentifier(IdentifierTree node, P p) {
         return null;
     }
 
+    /**
+     * {@inheritDoc} This implementation returns {@code null}.
+     *
+     * @param node  {@inheritDoc}
+     * @param p  {@inheritDoc}
+     * @return the result of scanning
+     */
     @Override
     public R visitInheritDoc(InheritDocTree node, P p) {
         return null;
     }
 
+    /**
+     * {@inheritDoc} This implementation scans the children in left to right order.
+     *
+     * @param node  {@inheritDoc}
+     * @param p  {@inheritDoc}
+     * @return the result of scanning
+     */
     @Override
     public R visitLink(LinkTree node, P p) {
         R r = scan(node.getReference(), p);
@@ -179,11 +273,25 @@ public class DocTreeScanner<R,P> implements DocTreeVisitor<R,P> {
         return r;
     }
 
+    /**
+     * {@inheritDoc} This implementation returns {@code null}.
+     *
+     * @param node  {@inheritDoc}
+     * @param p  {@inheritDoc}
+     * @return the result of scanning
+     */
     @Override
     public R visitLiteral(LiteralTree node, P p) {
         return null;
     }
 
+    /**
+     * {@inheritDoc} This implementation scans the children in left to right order.
+     *
+     * @param node  {@inheritDoc}
+     * @param p  {@inheritDoc}
+     * @return the result of scanning
+     */
     @Override
     public R visitParam(ParamTree node, P p) {
         R r = scan(node.getName(), p);
@@ -191,31 +299,73 @@ public class DocTreeScanner<R,P> implements DocTreeVisitor<R,P> {
         return r;
     }
 
+    /**
+     * {@inheritDoc} This implementation returns {@code null}.
+     *
+     * @param node  {@inheritDoc}
+     * @param p  {@inheritDoc}
+     * @return the result of scanning
+     */
     @Override
     public R visitReference(ReferenceTree node, P p) {
         return null;
     }
 
+    /**
+     * {@inheritDoc} This implementation scans the children in left to right order.
+     *
+     * @param node  {@inheritDoc}
+     * @param p  {@inheritDoc}
+     * @return the result of scanning
+     */
     @Override
     public R visitReturn(ReturnTree node, P p) {
         return scan(node.getDescription(), p);
     }
 
+    /**
+     * {@inheritDoc} This implementation scans the children in left to right order.
+     *
+     * @param node  {@inheritDoc}
+     * @param p  {@inheritDoc}
+     * @return the result of scanning
+     */
     @Override
     public R visitSee(SeeTree node, P p) {
         return scan(node.getReference(), p);
     }
 
+    /**
+     * {@inheritDoc} This implementation scans the children in left to right order.
+     *
+     * @param node  {@inheritDoc}
+     * @param p  {@inheritDoc}
+     * @return the result of scanning
+     */
     @Override
     public R visitSerial(SerialTree node, P p) {
         return scan(node.getDescription(), p);
     }
 
+    /**
+     * {@inheritDoc} This implementation scans the children in left to right order.
+     *
+     * @param node  {@inheritDoc}
+     * @param p  {@inheritDoc}
+     * @return the result of scanning
+     */
     @Override
     public R visitSerialData(SerialDataTree node, P p) {
         return scan(node.getDescription(), p);
     }
 
+    /**
+     * {@inheritDoc} This implementation scans the children in left to right order.
+     *
+     * @param node  {@inheritDoc}
+     * @param p  {@inheritDoc}
+     * @return the result of scanning
+     */
     @Override
     public R visitSerialField(SerialFieldTree node, P p) {
         R r = scan(node.getName(), p);
@@ -224,21 +374,49 @@ public class DocTreeScanner<R,P> implements DocTreeVisitor<R,P> {
         return r;
     }
 
+    /**
+     * {@inheritDoc} This implementation scans the children in left to right order.
+     *
+     * @param node  {@inheritDoc}
+     * @param p  {@inheritDoc}
+     * @return the result of scanning
+     */
     @Override
     public R visitSince(SinceTree node, P p) {
         return scan(node.getBody(), p);
     }
 
+    /**
+     * {@inheritDoc} This implementation scans the children in left to right order.
+     *
+     * @param node  {@inheritDoc}
+     * @param p  {@inheritDoc}
+     * @return the result of scanning
+     */
     @Override
     public R visitStartElement(StartElementTree node, P p) {
         return scan(node.getAttributes(), p);
     }
 
+    /**
+     * {@inheritDoc} This implementation returns {@code null}.
+     *
+     * @param node  {@inheritDoc}
+     * @param p  {@inheritDoc}
+     * @return the result of scanning
+     */
     @Override
     public R visitText(TextTree node, P p) {
         return null;
     }
 
+    /**
+     * {@inheritDoc} This implementation scans the children in left to right order.
+     *
+     * @param node  {@inheritDoc}
+     * @param p  {@inheritDoc}
+     * @return the result of scanning
+     */
     @Override
     public R visitThrows(ThrowsTree node, P p) {
         R r = scan(node.getExceptionName(), p);
@@ -246,26 +424,61 @@ public class DocTreeScanner<R,P> implements DocTreeVisitor<R,P> {
         return r;
     }
 
+    /**
+     * {@inheritDoc} This implementation scans the children in left to right order.
+     *
+     * @param node  {@inheritDoc}
+     * @param p  {@inheritDoc}
+     * @return the result of scanning
+     */
     @Override
     public R visitUnknownBlockTag(UnknownBlockTagTree node, P p) {
         return scan(node.getContent(), p);
     }
 
+    /**
+     * {@inheritDoc} This implementation scans the children in left to right order.
+     *
+     * @param node  {@inheritDoc}
+     * @param p  {@inheritDoc}
+     * @return the result of scanning
+     */
     @Override
     public R visitUnknownInlineTag(UnknownInlineTagTree node, P p) {
         return scan(node.getContent(), p);
     }
 
+    /**
+     * {@inheritDoc} This implementation scans the children in left to right order.
+     *
+     * @param node  {@inheritDoc}
+     * @param p  {@inheritDoc}
+     * @return the result of scanning
+     */
     @Override
     public R visitValue(ValueTree node, P p) {
         return scan(node.getReference(), p);
     }
 
+    /**
+     * {@inheritDoc} This implementation scans the children in left to right order.
+     *
+     * @param node  {@inheritDoc}
+     * @param p  {@inheritDoc}
+     * @return the result of scanning
+     */
     @Override
     public R visitVersion(VersionTree node, P p) {
         return scan(node.getBody(), p);
     }
 
+    /**
+     * {@inheritDoc} This implementation returns {@code null}.
+     *
+     * @param node  {@inheritDoc}
+     * @param p  {@inheritDoc}
+     * @return the result of scanning
+     */
     @Override
     public R visitOther(DocTree node, P p) {
         return null;

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2014, 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
@@ -40,8 +40,9 @@ import javax.tools.Diagnostic;
 @jdk.Exported
 public abstract class DocTrees extends Trees {
     /**
-     * Gets a DocTrees object for a given CompilationTask.
+     * Returns a DocTrees object for a given CompilationTask.
      * @param task the compilation task for which to get the Trees object
+     * @return the DocTrees object
      * @throws IllegalArgumentException if the task does not support the Trees API.
      */
     public static DocTrees instance(CompilationTask task) {
@@ -49,8 +50,9 @@ public abstract class DocTrees extends Trees {
     }
 
     /**
-     * Gets a DocTrees object for a given ProcessingEnvironment.
+     * Returns a DocTrees object for a given ProcessingEnvironment.
      * @param env the processing environment for which to get the Trees object
+     * @return the DocTrees object
      * @throws IllegalArgumentException if the env does not support the Trees API.
      */
     public static DocTrees instance(ProcessingEnvironment env) {
@@ -60,17 +62,26 @@ public abstract class DocTrees extends Trees {
     }
 
     /**
-     * Gets the doc comment tree, if any, for the Tree node identified by a given TreePath.
+     * Returns the doc comment tree, if any, for the Tree node identified by a given TreePath.
-     * Returns null if no doc comment was found.
+     * Returns {@code null} if no doc comment was found.
+     * @param path the path for the tree node
+     * @return the doc comment tree
      */
     public abstract DocCommentTree getDocCommentTree(TreePath path);
 
     /**
-     * Gets the language model element referred to by the leaf node of the given
+     * Returns the language model element referred to by the leaf node of the given
-     * {@link DocTreePath}, or null if unknown.
+     * {@link DocTreePath}, or {@code null} if unknown.
+     * @param path the path for the tree node
+     * @return the element
      */
     public abstract Element getElement(DocTreePath path);
 
+    /**
+     * Returns a utility object for accessing the source positions
+     * of documentation tree nodes.
+     * @return the utility object
+     */
     public abstract DocSourcePositions getSourcePositions();
 
     /**
@@ -80,6 +91,7 @@ public abstract class DocTrees extends Trees {
      * @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 c    the doc comment tree to use as a position hint
      * @param root the compilation unit that contains tree
      */
     public abstract void printMessage(Diagnostic.Kind kind, CharSequence msg,

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -52,7 +52,7 @@ import com.sun.tools.javac.util.Context;
 public abstract class JavacTask implements CompilationTask {
 
     /**
-     * Get the {@code JavacTask} for a {@code ProcessingEnvironment}.
+     * Returns the {@code JavacTask} for a {@code ProcessingEnvironment}.
      * If the compiler is being invoked using a
      * {@link javax.tools.JavaCompiler.CompilationTask CompilationTask},
      * then that task will be returned.
@@ -70,7 +70,7 @@ public abstract class JavacTask implements CompilationTask {
     }
 
     /**
-     * Parse the specified files returning a list of abstract syntax trees.
+     * Parses the specified files returning a list of abstract syntax trees.
      *
      * @return a list of abstract syntax trees
      * @throws IOException if an unhandled I/O error occurred in the compiler.
@@ -80,7 +80,7 @@ public abstract class JavacTask implements CompilationTask {
         throws IOException;
 
     /**
-     * Complete all analysis.
+     * Completes all analysis.
      *
      * @return a list of elements that were analyzed
      * @throws IOException if an unhandled I/O error occurred in the compiler.
@@ -89,7 +89,7 @@ public abstract class JavacTask implements CompilationTask {
     public abstract Iterable<? extends Element> analyze() throws IOException;
 
     /**
-     * Generate code.
+     * Generates code.
      *
      * @return a list of files that were generated
      * @throws IOException if an unhandled I/O error occurred in the compiler.
@@ -98,7 +98,7 @@ public abstract class JavacTask implements CompilationTask {
     public abstract Iterable<? extends JavaFileObject> generate() throws IOException;
 
     /**
-     * The specified listener will receive notification of events
+     * Sets a specified listener to receive notification of events
      * describing the progress of this compilation task.
      *
      * If another listener is receiving notifications as a result of a prior
@@ -108,46 +108,54 @@ public abstract class JavacTask implements CompilationTask {
      * any listener that has been previously set, followed by {@code addTaskListener}
      * for the new listener.
      *
+     * @param taskListener the task listener
      * @throws IllegalStateException if the specified listener has already been added.
      */
     public abstract void setTaskListener(TaskListener taskListener);
 
     /**
-     * The specified listener will receive notification of events
+     * Adds a specified listener so that it receives notification of events
      * describing the progress of this compilation task.
      *
      * This method may be called at any time before or during the compilation.
      *
+     * @param taskListener the task listener
      * @throws IllegalStateException if the specified listener has already been added.
      * @since 1.8
      */
     public abstract void addTaskListener(TaskListener taskListener);
 
     /**
-     * The specified listener will no longer receive notification of events
+     * Removes the specified listener so that it no longer receives
-     * describing the progress of this compilation task.
+     * notification of events describing the progress of this
+     * compilation task.
      *
      * This method may be called at any time before or during the compilation.
      *
+     * @param taskListener the task listener
      * @since 1.8
      */
     public abstract void removeTaskListener(TaskListener taskListener);
 
     /**
-     * Get a type mirror of the tree node determined by the specified path.
+     * Returns a type mirror of the tree node determined by the specified path.
      * This method has been superceded by methods on
      * {@link com.sun.source.util.Trees Trees}.
+     * @param path the path
+     * @return the type mirror
      * @see com.sun.source.util.Trees#getTypeMirror
      */
     public abstract TypeMirror getTypeMirror(Iterable<? extends Tree> path);
 
     /**
-     * Get a utility object for dealing with program elements.
+     * Returns a utility object for dealing with program elements.
+     * @return the utility object for dealing with program elements
      */
     public abstract Elements getElements();
 
     /**
-     * Get a utility object for dealing with type mirrors.
+     * Returns a utility object for dealing with type mirrors.
+     * @return the utility object for dealing with type mirrors
      */
     public abstract Types getTypes();
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -51,13 +51,13 @@ import javax.tools.StandardLocation;
 @jdk.Exported
 public interface Plugin {
     /**
-     * Get the user-friendly name of this plug-in.
+     * Returns the user-friendly name of this plug-in.
      * @return the user-friendly name of the plug-in
      */
     String getName();
 
     /**
-     * Initialize the plug-in for a given compilation task.
+     * Initializes the plug-in for a given compilation task.
      * @param task The compilation task that has just been started
      * @param args Arguments, if any, for the plug-in
      */

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -30,28 +30,63 @@ import com.sun.source.doctree.*;
 /**
  * A simple visitor for tree nodes.
  *
+ * @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
  */
 @jdk.Exported
 public class SimpleDocTreeVisitor<R,P> implements DocTreeVisitor<R, P> {
+    /**
+     * The default value, returned by the {@link #defaultAction default action}.
+     */
     protected final R DEFAULT_VALUE;
 
+    /**
+     * Creates a visitor, with a DEFAULT_VALUE of {@code null}.
+     */
     protected SimpleDocTreeVisitor() {
         DEFAULT_VALUE = null;
     }
 
+    /**
+     * Creates a visitor, with a specified DEFAULT_VALUE.
+     * @param defaultValue the default value to be returned by the default action.
+     */
     protected SimpleDocTreeVisitor(R defaultValue) {
         DEFAULT_VALUE = defaultValue;
     }
 
+    /**
+     * The default action, used by all visit methods that are not overridden.
+     * @param node the node being visited
+     * @param p the parameter value passed to the visit method
+     * @return the result value to be returned from the visit method
+     */
     protected R defaultAction(DocTree node, P p) {
         return DEFAULT_VALUE;
     }
 
+    /**
+     * Invokes the appropriate visit method specific to the type of the node.
+     * @param node the node on which to dispatch
+     * @param p a parameter to be passed to the appropriate visit method
+     * @return the value returns from the appropriate visit method
+     */
     public final R visit(DocTree node, P p) {
         return (node == null) ? null : node.accept(this, p);
     }
 
+    /**
+     * Invokes the appropriate visit method on each of a sequence of nodes.
+     * @param nodes the nodes on which to dispatch
+     * @param p a parameter value to be passed to each appropriate visit method
+     * @return the value return from the last of the visit methods, or null
+     *      if none were called.
+     */
     public final R visit(Iterable<? extends DocTree> nodes, P p) {
         R r = null;
         if (nodes != null) {
@@ -61,118 +96,350 @@ public class SimpleDocTreeVisitor<R,P> implements DocTreeVisitor<R, P> {
         return r;
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitAttribute(AttributeTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitAuthor(AuthorTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitComment(CommentTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitDeprecated(DeprecatedTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitDocComment(DocCommentTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitDocRoot(DocRootTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitEndElement(EndElementTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitEntity(EntityTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitErroneous(ErroneousTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitIdentifier(IdentifierTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitInheritDoc(InheritDocTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitLink(LinkTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitLiteral(LiteralTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitParam(ParamTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitReference(ReferenceTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitReturn(ReturnTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitSee(SeeTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitSerial(SerialTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitSerialData(SerialDataTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitSerialField(SerialFieldTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitSince(SinceTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitStartElement(StartElementTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitText(TextTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitThrows(ThrowsTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitUnknownBlockTag(UnknownBlockTagTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitUnknownInlineTag(UnknownInlineTagTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitValue(ValueTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitVersion(VersionTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitOther(DocTree node, P p) {
         return defaultAction(node, p);
     }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -30,29 +30,64 @@ import com.sun.source.tree.*;
 /**
  * A simple visitor for tree nodes.
  *
+ * @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.
+ *
  * @author Peter von der Ah&eacute;
  * @since 1.6
  */
 @jdk.Exported
 public class SimpleTreeVisitor <R,P> implements TreeVisitor<R,P> {
+    /**
+     * The default value, returned by the {@link #defaultAction default action}.
+     */
     protected final R DEFAULT_VALUE;
 
+    /**
+     * Creates a visitor, with a DEFAULT_VALUE of {@code null}.
+     */
     protected SimpleTreeVisitor() {
         DEFAULT_VALUE = null;
     }
 
+    /**
+     * Creates a visitor, with a specified DEFAULT_VALUE.
+     * @param defaultValue the default value to be returned by the default action.
+     */
     protected SimpleTreeVisitor(R defaultValue) {
         DEFAULT_VALUE = defaultValue;
     }
 
+    /**
+     * The default action, used by all visit methods that are not overridden.
+     * @param node the node being visited
+     * @param p the parameter value passed to the visit method
+     * @return the result value to be returned from the visit method
+     */
     protected R defaultAction(Tree node, P p) {
         return DEFAULT_VALUE;
     }
 
+    /**
+     * Invokes the appropriate visit method specific to the type of the node.
+     * @param node the node on which to dispatch
+     * @param p a parameter to be passed to the appropriate visit method
+     * @return the value returns from the appropriate visit method
+     */
     public final R visit(Tree node, P p) {
         return (node == null) ? null : node.accept(this, p);
     }
 
+    /**
+     * Invokes the appropriate visit method on each of a sequence of nodes.
+     * @param nodes the nodes on which to dispatch
+     * @param p a parameter value to be passed to each appropriate visit method
+     * @return the value return from the last of the visit methods, or null
+     *      if none were called.
+     */
     public final R visit(Iterable<? extends Tree> nodes, P p) {
         R r = null;
         if (nodes != null)
@@ -61,218 +96,650 @@ public class SimpleTreeVisitor <R,P> implements TreeVisitor<R,P> {
         return r;
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitCompilationUnit(CompilationUnitTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitPackage(PackageTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitImport(ImportTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitClass(ClassTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitMethod(MethodTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitVariable(VariableTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitEmptyStatement(EmptyStatementTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitBlock(BlockTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitDoWhileLoop(DoWhileLoopTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitWhileLoop(WhileLoopTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitForLoop(ForLoopTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitEnhancedForLoop(EnhancedForLoopTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitLabeledStatement(LabeledStatementTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitSwitch(SwitchTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitCase(CaseTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitSynchronized(SynchronizedTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitTry(TryTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitCatch(CatchTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitConditionalExpression(ConditionalExpressionTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitIf(IfTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitExpressionStatement(ExpressionStatementTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitBreak(BreakTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitContinue(ContinueTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitReturn(ReturnTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitThrow(ThrowTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitAssert(AssertTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitMethodInvocation(MethodInvocationTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitNewClass(NewClassTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitNewArray(NewArrayTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitLambdaExpression(LambdaExpressionTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitParenthesized(ParenthesizedTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitAssignment(AssignmentTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitCompoundAssignment(CompoundAssignmentTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitUnary(UnaryTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitBinary(BinaryTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitTypeCast(TypeCastTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitInstanceOf(InstanceOfTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitArrayAccess(ArrayAccessTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitMemberSelect(MemberSelectTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitMemberReference(MemberReferenceTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitIdentifier(IdentifierTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitLiteral(LiteralTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitPrimitiveType(PrimitiveTypeTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitArrayType(ArrayTypeTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitParameterizedType(ParameterizedTypeTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitUnionType(UnionTypeTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitIntersectionType(IntersectionTypeTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitTypeParameter(TypeParameterTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitWildcard(WildcardTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitModifiers(ModifiersTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitAnnotation(AnnotationTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitAnnotatedType(AnnotatedTypeTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitErroneous(ErroneousTree node, P p) {
         return defaultAction(node, p);
     }
 
+    /**
+     * {@inheritDoc} This implementation calls {@code defaultAction}.
+     *
+     * @param node {@inheritDoc}
+     * @param p {@inheritDoc}
+     * @return  the result of {@code defaultAction}
+     */
+    @Override
     public R visitOther(Tree node, P p) {
         return defaultAction(node, p);
     }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -39,7 +39,7 @@ import com.sun.source.tree.*;
 public interface SourcePositions {
 
     /**
-     * Gets the starting position of tree within file.  If tree is not found within
+     * Returns the starting position of tree within file.  If tree is not found within
      * file, or if the starting position is not available,
      * return {@link javax.tools.Diagnostic#NOPOS}.
      * The returned position must be at the start of the yield of this tree, that
@@ -58,7 +58,7 @@ public interface SourcePositions {
      long getStartPosition(CompilationUnitTree file, Tree tree);
 
     /**
-     * Gets the ending position of tree within file.  If tree is not found within
+     * Returns the ending position of tree within file.  If tree is not found within
      * file, or if the ending position is not available,
      * return {@link javax.tools.Diagnostic#NOPOS}.
      * The returned position must be at the end of the yield of this tree,

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

@@ -79,18 +79,45 @@ public final class TaskEvent
         COMPILATION,
     }
 
+    /**
+     * Creates a task event for a given kind.
+     * The source file, compilation unit and type element
+     * are all set to {@code null}.
+     * @param kind the kind of the event
+     */
     public TaskEvent(Kind kind) {
         this(kind, null, null, null);
     }
 
+    /**
+     * Creates a task event for a given kind and source file.
+     * The compilation unit and type element are both set to {@code null}.
+     * @param kind the kind of the event
+     * @param sourceFile the source file
+     */
     public TaskEvent(Kind kind, JavaFileObject sourceFile) {
         this(kind, sourceFile, null, null);
     }
 
+    /**
+     * Creates a task event for a given kind and compilation unit.
+     * The source file is set from the compilation unit,
+     * and the type element is set to {@code null}.
+     * @param kind the kind of the event
+     * @param unit the compilation unit
+     */
     public TaskEvent(Kind kind, CompilationUnitTree unit) {
         this(kind, unit.getSourceFile(), unit, null);
     }
 
+    /**
+     * Creates a task event for a given kind, compilation unit
+     * and type element.
+     * The source file is set from the compilation unit.
+     * @param kind the kind of the event
+     * @param unit the compilation unit
+     * @param clazz the type element
+     */
     public TaskEvent(Kind kind, CompilationUnitTree unit, TypeElement clazz) {
         this(kind, unit.getSourceFile(), unit, clazz);
     }
@@ -102,22 +129,42 @@ public final class TaskEvent
         this.clazz = clazz;
     }
 
+    /**
+     * Returns the kind for this event.
+     * @return the kind
+     */
     public Kind getKind() {
         return kind;
     }
 
+    /**
+     * Returns the source file for this event.
+     * May be {@code null}.
+     * @return the source file
+     */
     public JavaFileObject getSourceFile() {
         return file;
     }
 
+    /**
+     * Returns the compilation unit for this event.
+     * May be {@code null}.
+     * @return the compilation unit
+     */
     public CompilationUnitTree getCompilationUnit() {
         return unit;
     }
 
+    /**
+     * Returns the type element for this event.
+     * May be {@code null}.
+     * @return the type element
+     */
     public TypeElement getTypeElement() {
         return clazz;
     }
 
+    @Override
     public String toString() {
         return "TaskEvent["
             + kind + ","

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2014, 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
@@ -35,7 +35,15 @@ package com.sun.source.util;
 @jdk.Exported
 public interface TaskListener
 {
+    /**
+     * Invoked when an event has begun.
+     * @param e the event
+     */
     public void started(TaskEvent e);
 
+    /**
+     * Invoked when an event has been completed.
+     * @param e the event
+     */
     public void finished(TaskEvent e);
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2006, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2006, 2014, 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
@@ -39,16 +39,22 @@ import com.sun.source.tree.*;
 @jdk.Exported
 public class TreePath implements Iterable<Tree> {
     /**
-     * Gets a tree path for a tree node within a compilation unit.
+     * Returns a tree path for a tree node within a compilation unit,
-     * @return null if the node is not found
+     * or {@code null} if the node is not found.
+     * @param unit the compilation unit to search
+     * @param target the node to locate
+     * @return the tree path
      */
     public static TreePath getPath(CompilationUnitTree unit, Tree target) {
         return getPath(new TreePath(unit), target);
     }
 
     /**
-     * Gets a tree path for a tree node within a subtree identified by a TreePath object.
+     * Returns a tree path for a tree node within a subtree identified by a TreePath object.
-     * @return null if the node is not found
+     * Returns {@code null} if the node is not found.
+     * @param path the path in which to search
+     * @param target the node to locate
+     * @return the tree path of the target node
      */
     public static TreePath getPath(TreePath path, Tree target) {
         path.getClass();
@@ -85,41 +91,47 @@ public class TreePath implements Iterable<Tree> {
 
     /**
      * Creates a TreePath for a root node.
+     * @param node the root node
      */
-    public TreePath(CompilationUnitTree t) {
+    public TreePath(CompilationUnitTree node) {
-        this(null, t);
+        this(null, node);
     }
 
     /**
      * Creates a TreePath for a child node.
+     * @param path the parent path
+     * @param tree the child node
      */
-    public TreePath(TreePath p, Tree t) {
+    public TreePath(TreePath path, Tree tree) {
-        if (t.getKind() == Tree.Kind.COMPILATION_UNIT) {
+        if (tree.getKind() == Tree.Kind.COMPILATION_UNIT) {
-            compilationUnit = (CompilationUnitTree) t;
+            compilationUnit = (CompilationUnitTree) tree;
             parent = null;
         }
         else {
-            compilationUnit = p.compilationUnit;
+            compilationUnit = path.compilationUnit;
-            parent = p;
+            parent = path;
         }
-        leaf = t;
+        leaf = tree;
     }
     /**
-     * Get the compilation unit associated with this path.
+     * Returns the compilation unit associated with this path.
+     * @return the compilation unit
      */
     public CompilationUnitTree getCompilationUnit() {
         return compilationUnit;
     }
 
     /**
-     * Get the leaf node for this path.
+     * Returns the leaf node for this path.
+     * @return the leaf node
      */
     public Tree getLeaf() {
         return leaf;
     }
 
     /**
-     * Get the path for the enclosing node, or null if there is no enclosing node.
+     * Returns the path for the enclosing node, or {@code null} if there is no enclosing node.
+     * @return the path for the enclosing node
      */
     public TreePath getParentPath() {
         return parent;

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2006, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2006, 2014, 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
@@ -42,7 +42,10 @@ import com.sun.source.tree.*;
 public class TreePathScanner<R, P> extends TreeScanner<R, P> {
 
     /**
-     * Scan a tree from a position identified by a TreePath.
+     * Scans a tree from a position identified by a TreePath.
+     * @param path the path identifying the node to be scanned
+     * @param p a parameter value passed to visit methods
+     * @return the result value from the visit method
      */
     public R scan(TreePath path, P p) {
         this.path = path;
@@ -54,8 +57,9 @@ public class TreePathScanner<R, P> extends TreeScanner<R, P> {
     }
 
     /**
-     * Scan a single node.
+     * Scans a single node.
      * The current path is updated for the duration of the scan.
+     * @return the result value from the visit method
      */
     @Override
     public R scan(Tree tree, P p) {
@@ -72,8 +76,9 @@ public class TreePathScanner<R, P> extends TreeScanner<R, P> {
     }
 
     /**
-     * Get the current path for the node, as built up by the currently
+     * Returns the current path for the node, as built up by the currently
      * active set of scan calls.
+     * @return the current path
      */
     public TreePath getCurrentPath() {
         return path;