changeset 54502:d95d9d034034

6684386: ElementIterator javadoc bug Reviewed-by: psadhukhan
author serb
date Wed, 03 Apr 2019 15:56:29 -0700
parents d79e50159c0e
children e64a8477cd71
files src/java.desktop/share/classes/javax/swing/text/ElementIterator.java
diffstat 1 files changed, 62 insertions(+), 79 deletions(-) [+]
line wrap: on
line diff
--- a/src/java.desktop/share/classes/javax/swing/text/ElementIterator.java	Wed Apr 03 14:21:24 2019 +0530
+++ b/src/java.desktop/share/classes/javax/swing/text/ElementIterator.java	Wed Apr 03 15:56:29 2019 -0700
@@ -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.Enumeration;
 import java.util.Stack;
-import java.util.Enumeration;
 
 /**
+ * {@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
- * tree.  The constructor can be invoked with either Document or an Element
- * as an argument.  If the constructor is invoked with a Document as an
- * argument then the root of the iteration is the return value of
- * document.getDefaultRootElement().
- *
- * The iteration happens in a depth-first manner.  In terms of how
- * boundary conditions are handled:
- * a) if next() is called before first() or current(), the
- *    root will be returned.
- * b) next() returns null to indicate the end of the list.
- * c) previous() returns null when the current element is the root
- *    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
+ * The iteration happens in a depth-first manner. In terms of how boundary
+ * conditions are handled:
+ * <ul>
+ *   <li>if {@link #next} is called before {@link #first} or {@link #current},
+ *   the root will be returned
+ *   <li>{@link #next} returns {@code null} to indicate the end of the list
+ *   <li>{@link #previous} returns {@code null} when the current element is the
+ *   root or {@link #next} has returned {@code null}
+ * </ul>
+ * <p>
+ * The {@code ElementIterator} does no locking of the {@code 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:
- *
- *    public void iterate() {
- *        ElementIterator it = new ElementIterator(root);
- *        Element elem;
- *        while (true) {
- *           if ((elem = next()) != null) {
- *               // process element
- *               System.out.println("elem: " + elem.getName());
- *           } else {
- *               break;
- *           }
- *        }
- *    }
+ * <pre>{@code public void iterate() {
+ *      ElementIterator it = new ElementIterator(root);
+ *      Element elem;
+ *      while (true) {
+ *          if ((elem = it.next()) != null) {
+ *              // process element
+ *              System.out.println("elem: " + elem.getName());
+ *          } else {
+ *              break;
+ *          }
+ *      }
+ * }}</pre>
  *
  * @author Sunita Mani
- *
  */
-
 public class ElementIterator implements Cloneable {
 
-
     private Element root;
     private Stack<StackItem> elementStack = null;
 
     /**
-     * The StackItem class stores the element
-     * as well as a child index.  If the
-     * index is -1, then the element represented
-     * on the stack is the element itself.
-     * Otherwise, the index functions as an index
-     * into the vector of children of the element.
-     * In this case, the item on the stack
-     * represents the "index"th child of the element
-     *
+     * The {@code StackItem} class stores the element as well as a child index.
+     * If the index is -1, then the element represented on the stack is the
+     * element itself. Otherwise, the index functions as an index 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 @@
     }
 
     /**
-     * Creates a new ElementIterator. The
-     * root element is taken to get the
-     * default root element of the document.
+     * Creates a new {@code ElementIterator}. The root element is taken to get
+     * the 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 @@
         }
     }
 
-
     /**
      * Fetches the first element.
      *
-     * @return an Element.
+     * @return an {@code Element}
      */
     public Element first() {
         // just in case...
@@ -183,7 +172,7 @@
     /**
      * Fetches the current depth of element tree.
      *
-     * @return the depth.
+     * @return the depth
      */
     public int depth() {
         if (elementStack == null) {
@@ -192,12 +181,11 @@
         return elementStack.size();
     }
 
-
     /**
-     * Fetches the current Element.
+     * Fetches the current {@code Element}.
      *
-     * @return element on top of the stack or
-     *          <code>null</code> if the root element is <code>null</code>
+     * @return element on top of the stack or {@code null} if the root element
+     *         is {@code null}
      */
     public Element current() {
 
@@ -222,14 +210,11 @@
         return null;
     }
 
-
     /**
-     * Fetches the next Element. The strategy
-     * used to locate the next element is
-     * a depth-first search.
+     * Fetches the next {@code Element}. The strategy used to locate the next
+     * element is a depth-first search.
      *
-     * @return the next element or <code>null</code>
-     *          at the end of the list.
+     * @return the next element or {@code null} at the end of the list
      */
     public Element next() {
 
@@ -282,14 +267,12 @@
         return null;
     }
 
-
     /**
-     * Fetches the previous Element. If however the current
-     * element is the last element, or the current element
-     * is null, then null is returned.
+     * Fetches the previous {@code Element}. If however the current element is
+     * the last element, or the current element is {@code null}, then
+     * {@code null} is returned.
      *
-     * @return previous <code>Element</code> if available
-     *
+     * @return previous {@code Element} if available
      */
     public Element previous() {
 
@@ -335,8 +318,8 @@
     }
 
     /**
-     * Returns the last child of <code>parent</code> that is a leaf. If the
-     * last child is a not a leaf, this method is called with the last child.
+     * Returns the last child of {@code parent} that is a leaf. If the last
+     * 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 @@
         return getDeepestLeaf(parent.getElement(childCount - 1));
     }
 
-    /*
-      Iterates through the element tree and prints
-      out each element and its attributes.
-    */
+    /**
+     * Iterates through the element tree and prints out each element and its
+     * attributes.
+     */
     private void dumpTree() {
 
         Element elem;