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

[David Gilbert]

I added API docs to this class:

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

        * javax/swing/text/Segment.java: API docs all over.

Regards,

Dave

Index: javax/swing/text/Segment.java
===================================================================
RCS file: /sources/classpath/classpath/javax/swing/text/Segment.java,v
retrieving revision 1.8
diff -u -r1.8 Segment.java
--- javax/swing/text/Segment.java       19 Oct 2005 14:57:32 -0000      1.8
+++ javax/swing/text/Segment.java       23 Jan 2006 16:57:49 -0000
@@ -1,5 +1,5 @@
 /* Segment.java --
-   Copyright (C) 2002, 2004 Free Software Foundation, Inc.
+   Copyright (C) 2002, 2004, 2006 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -39,20 +39,40 @@
 
 import java.text.CharacterIterator;
 
+/**
+ * A text fragment represented by a sequence of characters stored in an array.
+ */
 public class Segment implements Cloneable, CharacterIterator
 {
   private boolean partialReturn;
+  
+  /** The current index. */
   private int current;
   
+  /** Storage for the characters (may contain additional characters). */
   public char[] array;
+  
+  /** The number of characters in the segment. */
   public int count;
+  
+  /** The offset of the first character in the segment. */
   public int offset;
 
+  /**
+   * Creates a new <code>Segment</code>.
+   */
   public Segment()
   {
     // Nothing to do here.
   }
 
+  /**
+   * Creates a new <code>Segment</code>.
+   * 
+   * @param array  the underlying character data.
+   * @param offset  the offset of the first character in the segment.
+   * @param count  the number of characters in the segment.
+   */
   public Segment(char[] array, int offset, int count)
   {
     this.array = array;
@@ -60,6 +80,12 @@
     this.count = count;
   }
   
+  /**
+   * Clones the segment (note that the underlying character array is not 
cloned,
+   * just the reference to it).
+   * 
+   * @return A clone of the segment.
+   */
   public Object clone()
   {
     try
@@ -72,6 +98,13 @@
       }
   }
 
+  /**
+   * Returns the character at the current index.  If the segment consists of
+   * zero characters, or the current index has passed the end of the 
+   * characters in the segment, this method returns address@hidden #DONE}.
+   * 
+   * @return The character at the current index.
+   */
   public char current()
   {
     if (count == 0
@@ -81,6 +114,14 @@
     return array[current];
   }
 
+  /**
+   * Sets the current index to the first character in the segment and returns
+   * that character.  If the segment contains zero characters, this method
+   * returns address@hidden #DONE}.
+   * 
+   * @return The first character in the segment, or address@hidden #DONE} if 
the 
+   *         segment contains zero characters.
+   */
   public char first()
   {
     if (count == 0)
@@ -90,21 +131,46 @@
     return array[current];
   }
 
+  /**
+   * Returns the index of the first character in the segment.
+   * 
+   * @return The index of the first character.
+   */
   public int getBeginIndex()
   {
     return offset;
   }
 
+  /**
+   * Returns the end index for the segment (one position beyond the last 
+   * character in the segment - note that this can be outside the range of the 
+   * underlying character array).
+   * 
+   * @return The end index for the segment.
+   */
   public int getEndIndex()
   {
     return offset + count;
   }
 
+  /**
+   * Returns the index of the current character in the segment.
+   * 
+   * @return The index of the current character.
+   */
   public int getIndex()
   {
     return current;
   }
 
+  /**
+   * Sets the current index to point to the last character in the segment and 
+   * returns that character.  If the segment contains zero characters, this 
+   * method returns address@hidden #DONE}.
+   * 
+   * @return The last character in the segment, or address@hidden #DONE} if 
the 
+   *         segment contains zero characters.
+   */
   public char last()
   {
     if (count == 0)
@@ -114,6 +180,17 @@
     return array[current];
   }
 
+  /**
+   * Sets the current index to point to the next character in the segment and 
+   * returns that character.  If the next character position is past the end of
+   * the segment, the index is set to address@hidden #getEndIndex()} and the 
method
+   * returns address@hidden #DONE}.  If the segment contains zero characters, 
this 
+   * method returns address@hidden #DONE}.
+   * 
+   * @return The next character in the segment or address@hidden #DONE} (if 
the next
+   *         character position is past the end of the segment or if the 
+   *         segment contains zero characters).
+   */
   public char next()
   {
     if (count == 0)
@@ -129,6 +206,16 @@
     return array[current];
   }
 
+  /**
+   * Sets the current index to point to the previous character in the segment 
+   * and returns that character.  If the current index is equal to 
+   * address@hidden #getBeginIndex()}, or if the segment contains zero 
characters, this 
+   * method returns address@hidden #DONE}.
+   * 
+   * @return The previous character in the segment or address@hidden #DONE} 
(if the 
+   *         current character position is at the beginning of the segment or 
+   *         if the segment contains zero characters).
+   */
   public char previous()
   {
     if (count == 0
@@ -139,6 +226,19 @@
     return array[current];
   }
 
+  /**
+   * Sets the current index and returns the character at that position (or
+   * address@hidden #DONE} if the index is equal to address@hidden 
#getEndIndex()}.
+   * 
+   * @param position  the current position.
+   * 
+   * @return The character at the specified <code>position</code>, or
+   *         address@hidden #DONE} if <code>position</code> is equal to 
+   *         address@hidden #getEndIndex()}.
+   *         
+   * @throws IllegalArgumentException if <code>position</code> is not in the
+   *         range address@hidden #getBeginIndex()} to address@hidden 
#getEndIndex()}.
+   */
   public char setIndex(int position)
   {
     if (position < getBeginIndex()
@@ -153,12 +253,23 @@
     return array[current];
   }
 
+  /**
+   * Returns a <code>String</code> containing the same characters as this 
+   * <code>Segment</code>.
+   * 
+   * @return A <code>String</code> containing the same characters as this 
+   *         <code>Segment</code>.
+   */
   public String toString()
   {
     return new String(array, offset, count);
   }
 
   /**
+   * Sets the partial return flag.
+   * 
+   * @param p  the new value of the flag.
+   * 
    * @since 1.4
    */
   public void setPartialReturn(boolean p)
@@ -167,6 +278,9 @@
   }
   
   /**
+   * Returns the partial return flag.
+   * 
+   * @return The partial return flag.
    * @since 1.4
    */
   public boolean isPartialReturn()