[cp-patches] FYI: javax.swing.text.StringContent.java: API docs

[David Gilbert]

I committed this patch:

2006-01-24  David Gilbert  <address@hidden>

        * javax/swing/text/StringContent.java: Added API docs all over, plus
        minor reformatting.

Regards,

Dave

Index: javax/swing/text/StringContent.java
===================================================================
RCS file: /sources/classpath/classpath/javax/swing/text/StringContent.java,v
retrieving revision 1.6
diff -u -r1.6 StringContent.java
--- javax/swing/text/StringContent.java 24 Jan 2006 14:06:11 -0000      1.6
+++ javax/swing/text/StringContent.java 24 Jan 2006 14:30:44 -0000
@@ -54,7 +54,8 @@
  * 
  * <p>Do not use this class for large size.</p>
  */
-public final class StringContent implements AbstractDocument.Content, 
Serializable
+public final class StringContent 
+  implements AbstractDocument.Content, Serializable
 {
   /** The serialization UID (compatible with JDK1.5). */
   private static final long serialVersionUID = 4755994433709540381L;
@@ -87,7 +88,8 @@
       try
         {
           StringContent.this.checkLocation(this.start, this.length);
-          this.redoContent = new String(StringContent.this.content, 
this.start, this.length);
+          this.redoContent = new String(StringContent.this.content, this.start,
+              this.length);
           StringContent.this.remove(this.start, this.length);
         }
       catch (BadLocationException b)
@@ -175,11 +177,20 @@
     }
   }
 
+  /**
+   * Creates a new instance containing the string "\n".
+   */
   public StringContent()
   {
     this(1);
   }
 
+  /**
+   * Creates a new instance containing the string "\n".
+   * 
+   * @param initialLength  the initial length of the underlying character 
+   *                       array used to store the content.
+   */
   public StringContent(int initialLength)
   {
     super();
@@ -198,7 +209,7 @@
     Iterator iter = this.positions.iterator();
     while(iter.hasNext())
       {
-        Position p = (Position)iter.next();
+        Position p = (Position) iter.next();
         if ((offset <= p.getOffset())
             && (p.getOffset() <= (offset + length)))
           refPos.add(p);
@@ -206,6 +217,16 @@
     return refPos;
   }
 
+  /**
+   * Creates a position reference for the character at the given offset.  The
+   * position offset will be automatically updated when new characters are
+   * inserted into or removed from the content.
+   * 
+   * @param offset  the character offset.
+   * 
+   * @throws BadLocationException if offset is outside the bounds of the 
+   *         content.
+   */
   public Position createPosition(int offset) throws BadLocationException
   {
     if (offset < this.count || offset > this.count)
@@ -215,11 +236,27 @@
     return sp;
   }
   
+  /**
+   * Returns the length of the string content, including the '\n' character at
+   * the end.
+   * 
+   * @return The length of the string content.
+   */
   public int length()
   {
     return this.count;
   }
   
+  /**
+   * Inserts <code>str</code> at the given position and returns an 
+   * address@hidden UndoableEdit} that enables undo/redo support.
+   * 
+   * @param where  the insertion point (must be less than 
+   *               <code>length()</code>).
+   * @param str  the string to insert (<code>null</code> not permitted).
+   * 
+   * @return An object that can undo the insertion.
+   */
   public UndoableEdit insertString(int where, String str)
     throws BadLocationException
   {
@@ -235,13 +272,15 @@
     if (where > 0)
       System.arraycopy(this.content, 0, temp, 0, where);
     System.arraycopy(insert, 0, temp, where, insert.length);
-    System.arraycopy(this.content, where, temp, (where + insert.length), 
(temp.length - where - insert.length));
+    System.arraycopy(this.content, where, temp, (where + insert.length), 
+        (temp.length - where - insert.length));
     if (this.content.length < temp.length)
       this.content = new char[temp.length];
     // Copy the result in the original char array.
     System.arraycopy(temp, 0, this.content, 0, temp.length);
     // Move all the positions.
-    Vector refPos = getPositionsInRange(this.positions, where, temp.length - 
where);
+    Vector refPos = getPositionsInRange(this.positions, where, 
+                                        temp.length - where);
     Iterator iter = refPos.iterator();
     while (iter.hasNext())
       {
@@ -252,20 +291,35 @@
     return iundo;
   }
   
+  /**
+   * Removes the specified range of characters and returns an 
+   * address@hidden UndoableEdit} that enables undo/redo support.
+   * 
+   * @param where  the starting index.
+   * @param nitems  the number of characters.
+   * 
+   * @return An object that can undo the removal.
+   * 
+   * @throws BadLocationException if the character range extends outside the
+   *         bounds of the content OR includes the last character.
+   */
   public UndoableEdit remove(int where, int nitems) throws BadLocationException
   {
     checkLocation(where, nitems + 1);
     char[] temp = new char[(this.content.length - nitems)];
     this.count = this.count - nitems;
-    RemoveUndo rundo = new RemoveUndo(where, new String(this.content, where, 
nitems));
+    RemoveUndo rundo = new RemoveUndo(where, new String(this.content, where, 
+        nitems));
     // Copy array.
     System.arraycopy(this.content, 0, temp, 0, where);
-    System.arraycopy(this.content, where + nitems, temp, where, 
this.content.length - where - nitems);
+    System.arraycopy(this.content, where + nitems, temp, where, 
+        this.content.length - where - nitems);
     this.content = new char[temp.length];
     // Then copy the result in the original char array.
     System.arraycopy(temp, 0, this.content, 0, this.content.length);
     // Move all the positions.
-    Vector refPos = getPositionsInRange(this.positions, where, 
this.content.length + nitems - where);
+    Vector refPos = getPositionsInRange(this.positions, where, 
+        this.content.length + nitems - where);
     Iterator iter = refPos.iterator();
     while (iter.hasNext())
       {
@@ -278,10 +332,22 @@
     return rundo;
   }
   
+  /**
+   * Returns a new <code>String</code> containing the characters in the 
+   * specified range.
+   * 
+   * @param where  the start index.
+   * @param len  the number of characters.
+   * 
+   * @return A string.
+   * 
+   * @throws BadLocationException if the requested range of characters extends 
+   *         outside the bounds of the content.
+   */
   public String getString(int where, int len) throws BadLocationException
   {
     checkLocation(where, len);
-    return new String (this.content, where, len);
+    return new String(this.content, where, len);
   }
   
   /**