6684386: ElementIterator javadoc bug

Reviewed-by: psadhukhan

src/java.desktop/share/classes/javax/swing/text/ElementIterator.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2019, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -25,65 +25,58 @@
 
 package javax.swing.text;
 
-import java.util.Stack;
 import java.util.Enumeration;
+import java.util.Stack;
 
 /**
+ * {@code ElementIterator}, as the name suggests, iterates over the
+ * {@code Element} tree. The constructor can be invoked with either
+ * {@code Document} or an {@code Element} as an argument. If the constructor is
+ * invoked with a {@code Document} as an argument then the root of the iteration
+ * is the return value of {@code document.getDefaultRootElement()}.
  * <p>
- * ElementIterator, as the name suggests, iterates over the Element
+ * The iteration happens in a depth-first manner. In terms of how boundary
- * tree.  The constructor can be invoked with either Document or an Element
+ * conditions are handled:
- * as an argument.  If the constructor is invoked with a Document as an
+ * <ul>
- * argument then the root of the iteration is the return value of
+ *   <li>if {@link #next} is called before {@link #first} or {@link #current},
- * document.getDefaultRootElement().
+ *   the root will be returned
- *
+ *   <li>{@link #next} returns {@code null} to indicate the end of the list
- * The iteration happens in a depth-first manner.  In terms of how
+ *   <li>{@link #previous} returns {@code null} when the current element is the
- * boundary conditions are handled:
+ *   root or {@link #next} has returned {@code null}
- * a) if next() is called before first() or current(), the
+ * </ul>
- *    root will be returned.
+ * <p>
- * b) next() returns null to indicate the end of the list.
+ * The {@code ElementIterator} does no locking of the {@code Element} tree. This
- * c) previous() returns null when the current element is the root
+ * means that it does not track any changes. It is the responsibility of the
- *    or next() has returned null.
- *
- * The ElementIterator does no locking of the Element tree. This means
- * that it does not track any changes.  It is the responsibility of the
  * user of this class, to ensure that no changes happen during element
  * iteration.
- *
+ * <p>
  * Simple usage example:
- *
+ * <pre>{@code public void iterate() {
- *    public void iterate() {
+ *      ElementIterator it = new ElementIterator(root);
- *        ElementIterator it = new ElementIterator(root);
+ *      Element elem;
- *        Element elem;
+ *      while (true) {
- *        while (true) {
+ *          if ((elem = it.next()) != null) {
- *           if ((elem = next()) != null) {
+ *              // process element
- *               // process element
+ *              System.out.println("elem: " + elem.getName());
- *               System.out.println("elem: " + elem.getName());
+ *          } else {
- *           } else {
+ *              break;
- *               break;
+ *          }
- *           }
+ *      }
- *        }
+ * }}</pre>
- *    }
  *
  * @author Sunita Mani
- *
  */
-
 public class ElementIterator implements Cloneable {
 
-
     private Element root;
     private Stack<StackItem> elementStack = null;
 
     /**
-     * The StackItem class stores the element
+     * The {@code StackItem} class stores the element as well as a child index.
-     * as well as a child index.  If the
+     * If the index is -1, then the element represented on the stack is the
-     * index is -1, then the element represented
+     * element itself. Otherwise, the index functions as an index into the
-     * on the stack is the element itself.
+     * vector of children of the element. In this case, the item on the stack
-     * Otherwise, the index functions as an index
+     * represents the "index"th child of the element.
-     * into the vector of children of the element.
-     * In this case, the item on the stack
-     * represents the "index"th child of the element
-     *
      */
     private class StackItem implements Cloneable {
         Element item;
@@ -117,31 +110,28 @@ public class ElementIterator implements Cloneable {
     }
 
     /**
-     * Creates a new ElementIterator. The
+     * Creates a new {@code ElementIterator}. The root element is taken to get
-     * root element is taken to get the
+     * the default root element of the document.
-     * default root element of the document.
      *
-     * @param document a Document.
+     * @param  document a {@code Document}
      */
     public ElementIterator(Document document) {
         root = document.getDefaultRootElement();
     }
 
-
     /**
-     * Creates a new ElementIterator.
+     * Creates a new {@code ElementIterator}.
      *
-     * @param root the root Element.
+     * @param  root the root {@code Element}
      */
     public ElementIterator(Element root) {
         this.root = root;
     }
 
-
     /**
-     * Clones the ElementIterator.
+     * Clones the {@code ElementIterator}.
      *
-     * @return a cloned ElementIterator Object.
+     * @return a cloned {@code ElementIterator} Object
      */
     public synchronized Object clone() {
 
@@ -161,11 +151,10 @@ public class ElementIterator implements Cloneable {
         }
     }
 
-
     /**
      * Fetches the first element.
      *
-     * @return an Element.
+     * @return an {@code Element}
      */
     public Element first() {
         // just in case...
@@ -183,7 +172,7 @@ public class ElementIterator implements Cloneable {
     /**
      * Fetches the current depth of element tree.
      *
-     * @return the depth.
+     * @return the depth
      */
     public int depth() {
         if (elementStack == null) {
@@ -192,12 +181,11 @@ public class ElementIterator implements Cloneable {
         return elementStack.size();
     }
 
-
     /**
-     * Fetches the current Element.
+     * Fetches the current {@code Element}.
      *
-     * @return element on top of the stack or
+     * @return element on top of the stack or {@code null} if the root element
-     *          <code>null</code> if the root element is <code>null</code>
+     *         is {@code null}
      */
     public Element current() {
 
@@ -222,14 +210,11 @@ public class ElementIterator implements Cloneable {
         return null;
     }
 
-
     /**
-     * Fetches the next Element. The strategy
+     * Fetches the next {@code Element}. The strategy used to locate the next
-     * used to locate the next element is
+     * element is a depth-first search.
-     * a depth-first search.
      *
-     * @return the next element or <code>null</code>
+     * @return the next element or {@code null} at the end of the list
-     *          at the end of the list.
      */
     public Element next() {
 
@@ -282,14 +267,12 @@ public class ElementIterator implements Cloneable {
         return null;
     }
 
-
     /**
-     * Fetches the previous Element. If however the current
+     * Fetches the previous {@code Element}. If however the current element is
-     * element is the last element, or the current element
+     * the last element, or the current element is {@code null}, then
-     * is null, then null is returned.
+     * {@code null} is returned.
-     *
-     * @return previous <code>Element</code> if available
      *
+     * @return previous {@code Element} if available
      */
     public Element previous() {
 
@@ -335,8 +318,8 @@ public class ElementIterator implements Cloneable {
     }
 
     /**
-     * Returns the last child of <code>parent</code> that is a leaf. If the
+     * Returns the last child of {@code parent} that is a leaf. If the last
-     * last child is a not a leaf, this method is called with the last child.
+     * child is a not a leaf, this method is called with the last child.
      */
     private Element getDeepestLeaf(Element parent) {
         if (parent.isLeaf()) {
@@ -349,10 +332,10 @@ public class ElementIterator implements Cloneable {
         return getDeepestLeaf(parent.getElement(childCount - 1));
     }
 
-    /*
+    /**
-      Iterates through the element tree and prints
+     * Iterates through the element tree and prints out each element and its
-      out each element and its attributes.
+     * attributes.
-    */
+     */
     private void dumpTree() {
 
         Element elem;