harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r772552 [1/5] - /harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/
Date Thu, 07 May 2009 08:42:03 GMT
Author: tellison
Date: Thu May  7 08:42:00 2009
New Revision: 772552

URL: http://svn.apache.org/viewvc?rev=772552&view=rev
Log:
Apply partial patch for HARMONY-6189 (Javadocs for java.text.*)

Modified:
    harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/Annotation.java
    harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/AttributedCharacterIterator.java
    harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/AttributedString.java
    harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/Bidi.java
    harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/BreakIterator.java
    harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/CharacterIterator.java
    harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/ChoiceFormat.java
    harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/CollationElementIterator.java
    harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/CollationKey.java
    harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/Collator.java
    harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DateFormat.java
    harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DateFormatSymbols.java
    harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DecimalFormat.java
    harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DecimalFormatSymbols.java
    harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/FieldPosition.java
    harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/Format.java
    harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/MessageFormat.java
    harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/NumberFormat.java
    harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/ParseException.java
    harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/ParsePosition.java
    harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/RuleBasedCollator.java
    harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/SimpleDateFormat.java
    harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/StringCharacterIterator.java

Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/Annotation.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/Annotation.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/Annotation.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/Annotation.java Thu May  7 08:42:00 2009
@@ -18,20 +18,50 @@
 package java.text;
 
 /**
- * Annotation
+ * Wrapper for a text attribute value which represents an annotation. An
+ * annotation has two special aspects:
+ * <ol>
+ * <li>it is connected to a range of main text; if this range or the main text
+ * is changed then the annotation becomes invalid,</li>
+ * <li>it can not be joined with adjacent annotations even if the text attribute
+ * value is the same.</li>
+ * </ol>
+ * <p>
+ * By wrapping text attribute values into an {@code Annotation}, these aspects
+ * will be taken into account when handling annotation text and the
+ * corresponding main text.
+ * <p>
+ * Note: There is no semantic connection between this annotation class and the
+ * {@code java.lang.annotation} package.
  */
 public class Annotation {
 
     private Object value;
 
+    /**
+     * Constructs a new {@code Annotation}.
+     *
+     * @param attribute the attribute attached to this annotation. This may be
+     *        {@code null}.
+     */
     public Annotation(Object attribute) {
         value = attribute;
     }
 
+    /**
+     * Returns the value of this annotation. The value may be {@code null}.
+     *
+     * @return the value of this annotation or {@code null}.
+     */
     public Object getValue() {
         return value;
     }
 
+    /**
+     * Returns this annotation in string representation.
+     *
+     * @return the string representation of this annotation.
+     */
     @Override
     public String toString() {
         return getClass().getName() + "[value=" + value + ']'; //$NON-NLS-1$

Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/AttributedCharacterIterator.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/AttributedCharacterIterator.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/AttributedCharacterIterator.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/AttributedCharacterIterator.java Thu May  7 08:42:00 2009
@@ -25,27 +25,68 @@
 import org.apache.harmony.text.internal.nls.Messages;
 
 /**
- * AttributedCharacterIterator
+ * Extends the
+ * {@link CharacterIterator} interface, adding support for iterating over
+ * attributes and not only characters. An
+ * {@code AttributedCharacterIterator} also allows the user to find runs and
+ * their limits. Runs are defined as ranges of characters that all have the same
+ * attributes with the same values.
  */
 public interface AttributedCharacterIterator extends CharacterIterator {
 
+    /**
+     * Defines keys for text attributes.
+     */
     public static class Attribute implements Serializable {
 
         private static final long serialVersionUID = -9142742483513960612L;
 
+        /**
+         * This attribute marks segments from an input method. Most input
+         * methods create these segments for words.
+         *
+         * The value objects are of the type {@code Annotation} which contain
+         * {@code null}.
+         */
         public static final Attribute INPUT_METHOD_SEGMENT = new Attribute(
                 "input_method_segment"); //$NON-NLS-1$
 
+        /**
+         * The attribute describing the language of a character. The value
+         * objects are of type {@code Locale} or a subtype of it.
+         */
         public static final Attribute LANGUAGE = new Attribute("language"); //$NON-NLS-1$
 
+        /**
+         * For languages that have different reading directions of text (like
+         * Japanese), this attribute allows to define which reading should be
+         * used. The value objects are of type {@code Annotation} which
+         * contain a {@code String}.
+         */
         public static final Attribute READING = new Attribute("reading"); //$NON-NLS-1$
 
         private String name;
 
+        /**
+         * The constructor for an {@code Attribute} with the name passed.
+         *
+         * @param name
+         *            the name of the new {@code Attribute}.
+         */
         protected Attribute(String name) {
             this.name = name;
         }
 
+        /**
+         * Compares this attribute with the specified object. Checks if both
+         * objects are the same instance. It is defined final so all subclasses
+         * have the same behavior for this method.
+         *
+         * @param object
+         *            the object to compare against.
+         * @return {@code true} if the object passed is equal to this instance;
+         *         {@code false} otherwise.
+         */
         @Override
         public final boolean equals(Object object) {
             if (object == null || !(object.getClass().equals(this.getClass()))) {
@@ -54,15 +95,35 @@
             return name.equals(((Attribute) object).name);
         }
 
+        /**
+         * Returns the name of this attribute.
+         *
+         * @return the name of this attribute.
+         */
         protected String getName() {
             return name;
         }
 
+        /**
+         * Calculates the hash code for objects of type {@code Attribute}. It
+         * is defined final so all sub types calculate their hash code
+         * identically.
+         *
+         * @return the hash code for this instance of {@code Attribute}.
+         */
         @Override
         public final int hashCode() {
             return name.hashCode();
         }
 
+        /**
+         * Resolves a deserialized instance to the correct constant attribute.
+         *
+         * @return the {@code Attribute} this instance represents.
+         * @throws InvalidObjectException
+         *             if this instance is not of type {@code Attribute.class}
+         *             or if it is not a known {@code Attribute}.
+         */
         protected Object readResolve() throws InvalidObjectException {
             if (this.getClass() != Attribute.class) {
                 // text.0C=cannot resolve subclasses
@@ -81,27 +142,100 @@
             throw new InvalidObjectException(Messages.getString("text.02")); //$NON-NLS-1$
         }
 
+        /**
+         * Returns the name of the class followed by a "(", the name of the
+         * attribute, and a ")".
+         *
+         * @return the string representing this instance.
+         */
         @Override
         public String toString() {
             return getClass().getName() + '(' + getName() + ')';
         }
     }
 
+    /**
+     * Returns a set of attributes present in the {@code
+     * AttributedCharacterIterator}. An empty set is returned if no attributes
+     * were defined.
+     *
+     * @return a set of attribute keys; may be empty.
+     */
     public Set<Attribute> getAllAttributeKeys();
 
+    /**
+     * Returns the value stored in the attribute for the current character. If
+     * the attribute was not defined then {@code null} is returned.
+     *
+     * @param attribute the attribute for which the value should be returned.
+     * @return the value of the requested attribute for the current character or
+     *         {@code null} if it was not defined.
+     */
     public Object getAttribute(Attribute attribute);
 
+    /**
+     * Returns a map of all attributes of the current character. If no
+     * attributes were defined for the current character then an empty map is
+     * returned.
+     *
+     * @return a map of all attributes for the current character or an empty
+     *         map.
+     */
     public Map<Attribute, Object> getAttributes();
 
+    /**
+     * Returns the index of the last character in the run having the same
+     * attributes as the current character.
+     *
+     * @return the index of the last character of the current run.
+     */
     public int getRunLimit();
 
+    /**
+     * Returns the index of the last character in the run that has the same
+     * attribute value for the given attribute as the current character.
+     *
+     * @param attribute
+     *            the attribute which the run is based on.
+     * @return the index of the last character of the current run.
+     */
     public int getRunLimit(Attribute attribute);
 
+    /**
+     * Returns the index of the last character in the run that has the same
+     * attribute values for the attributes in the set as the current character.
+     *
+     * @param attributes
+     *            the set of attributes which the run is based on.
+     * @return the index of the last character of the current run.
+     */
     public int getRunLimit(Set<? extends Attribute> attributes);
 
+    /**
+     * Returns the index of the first character in the run that has the same
+     * attributes as the current character.
+     *
+     * @return the index of the last character of the current run.
+     */
     public int getRunStart();
 
+    /**
+     * Returns the index of the first character in the run that has the same
+     * attribute value for the given attribute as the current character.
+     *
+     * @param attribute
+     *            the attribute which the run is based on.
+     * @return the index of the last character of the current run.
+     */
     public int getRunStart(Attribute attribute);
 
+    /**
+     * Returns the index of the first character in the run that has the same
+     * attribute values for the attributes in the set as the current character.
+     *
+     * @param attributes
+     *            the set of attributes which the run is based on.
+     * @return the index of the last character of the current run.
+     */
     public int getRunStart(Set<? extends Attribute> attributes);
 }

Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/AttributedString.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/AttributedString.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/AttributedString.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/AttributedString.java Thu May  7 08:42:00 2009
@@ -31,7 +31,8 @@
 import org.apache.harmony.text.internal.nls.Messages;
 
 /**
- * AttributedString
+ * Holds a string with attributes describing the characters of
+ * this string.
  */
 public class AttributedString {
 
@@ -89,11 +90,10 @@
         }
 
         /**
-         * Answers a new StringCharacterIterator with the same source String,
-         * begin, end, and current index as this StringCharacterIterator.
-         * 
-         * @return a shallow copy of this StringCharacterIterator
+         * Returns a new {@code AttributedIterator} with the same source string,
+         * begin, end, and current index as this attributed iterator.
          * 
+         * @return a shallow copy of this attributed iterator.
          * @see java.lang.Cloneable
          */
         @Override
@@ -111,12 +111,6 @@
             }
         }
 
-        /**
-         * Answers the character at the current index in the source String.
-         * 
-         * @return the current character, or DONE if the current index is past
-         *         the end
-         */
         public char current() {
             if (offset == end) {
                 return DONE;
@@ -124,12 +118,6 @@
             return attrString.text.charAt(offset);
         }
 
-        /**
-         * Sets the current position to the begin index and answers the
-         * character at the begin index.
-         * 
-         * @return the character at the begin index
-         */
         public char first() {
             if (begin == end) {
                 return DONE;
@@ -139,27 +127,27 @@
         }
 
         /**
-         * Answers the begin index in the source String.
+         * Returns the begin index in the source string.
          * 
-         * @return the index of the first character to iterate
+         * @return the index of the first character to iterate.
          */
         public int getBeginIndex() {
             return begin;
         }
 
         /**
-         * Answers the end index in the source String.
+         * Returns the end index in the source String.
          * 
-         * @return the index one past the last character to iterate
+         * @return the index one past the last character to iterate.
          */
         public int getEndIndex() {
             return end;
         }
 
         /**
-         * Answers the current index in the source String.
+         * Returns the current index in the source String.
          * 
-         * @return the current index
+         * @return the current index.
          */
         public int getIndex() {
             return offset;
@@ -188,6 +176,12 @@
             return false;
         }
 
+        /**
+         * Returns a set of attributes present in the {@code AttributedString}.
+         * An empty set returned indicates that no attributes where defined.
+         *
+         * @return a set of attribute keys that may be empty.
+         */
         public Set<AttributedIterator.Attribute> getAllAttributeKeys() {
             if (begin == 0 && end == attrString.text.length()
                     && attributesAllowed == null) {
@@ -350,12 +344,6 @@
             return start;
         }
 
-        /**
-         * Sets the current position to the end index - 1 and answers the
-         * character at the current position.
-         * 
-         * @return the character before the end index
-         */
         public char last() {
             if (begin == end) {
                 return DONE;
@@ -364,13 +352,6 @@
             return attrString.text.charAt(offset);
         }
 
-        /**
-         * Increments the current index and returns the character at the new
-         * index.
-         * 
-         * @return the character at the next index, or DONE if the next index is
-         *         past the end
-         */
         public char next() {
             if (offset >= (end - 1)) {
                 offset = end;
@@ -379,13 +360,6 @@
             return attrString.text.charAt(++offset);
         }
 
-        /**
-         * Decrements the current index and returns the character at the new
-         * index.
-         * 
-         * @return the character at the previous index, or DONE if the previous
-         *         index is past the beginning
-         */
         public char previous() {
             if (offset == begin) {
                 return DONE;
@@ -393,16 +367,6 @@
             return attrString.text.charAt(--offset);
         }
 
-        /**
-         * Sets the current index in the source String.
-         * 
-         * @return the character at the new index, or DONE if the index is past
-         *         the end
-         * 
-         * @exception IllegalArgumentException
-         *                when the new index is less than the begin index or
-         *                greater than the end index
-         */
         public char setIndex(int location) {
             if (location < begin || location > end) {
                 throw new IllegalArgumentException();
@@ -415,6 +379,14 @@
         }
     }
 
+    /**
+     * Constructs an {@code AttributedString} from an {@code
+     * AttributedCharacterIterator}, which represents attributed text.
+     *
+     * @param iterator
+     *            the {@code AttributedCharacterIterator} that contains the text
+     *            for this attributed string.
+     */
     public AttributedString(AttributedCharacterIterator iterator) {
         if (iterator.getBeginIndex() > iterator.getEndIndex()) {
             // text.0A=Invalid substring range
@@ -490,17 +462,63 @@
         }
     }
 
+    /**
+     * Constructs an {@code AttributedString} from a range of the text contained
+     * in the specified {@code AttributedCharacterIterator}, starting at {@code
+     * start} and ending at {@code end}. All attributes will be copied to this
+     * attributed string.
+     *
+     * @param iterator
+     *            the {@code AttributedCharacterIterator} that contains the text
+     *            for this attributed string.
+     * @param start
+     *            the start index of the range of the copied text.
+     * @param end
+     *            the end index of the range of the copied text.
+     * @throws IllegalArgumentException
+     *             if {@code start} is less than first index of
+     *             {@code iterator}, {@code end} is greater than the last
+     *             index + 1 in {@code iterator} or if {@code start > end}.
+     */
     public AttributedString(AttributedCharacterIterator iterator, int start,
             int end) {
         this(iterator, start, end, iterator.getAllAttributeKeys());
     }
 
+    /**
+     * Constructs an {@code AttributedString} from a range of the text contained
+     * in the specified {@code AttributedCharacterIterator}, starting at {@code
+     * start}, ending at {@code end} and it will copy the attributes defined in
+     * the specified set. If the set is {@code null} then all attributes are
+     * copied.
+     *
+     * @param iterator
+     *            the {@code AttributedCharacterIterator} that contains the text
+     *            for this attributed string.
+     * @param start
+     *            the start index of the range of the copied text.
+     * @param end
+     *            the end index of the range of the copied text.
+     * @param attributes
+     *            the set of attributes that will be copied, or all if it is
+     *            {@code null}.
+     * @throws IllegalArgumentException
+     *             if {@code start} is less than first index of
+     *             {@code iterator}, {@code end} is greater than the last index +
+     *             1 in {@code iterator} or if {@code start > end}.
+     */
     public AttributedString(AttributedCharacterIterator iterator, int start,
             int end, AttributedCharacterIterator.Attribute[] attributes) {
         this(iterator, start, end, new HashSet<Attribute>(Arrays
                 .asList(attributes)));
     }
 
+    /**
+     * Creates an {@code AttributedString} from the given text.
+     *
+     * @param value
+     *            the text to take as base for this attributed string.
+     */
     public AttributedString(String value) {
         if (value == null) {
             throw new NullPointerException();
@@ -509,6 +527,20 @@
         attributeMap = new HashMap<Attribute, List<Range>>(11);
     }
 
+    /**
+     * Creates an {@code AttributedString} from the given text and the
+     * attributes. The whole text has the given attributes applied.
+     *
+     * @param value
+     *            the text to take as base for this attributed string.
+     * @param attributes
+     *            the attributes that the text is associated with.
+     * @throws IllegalArgumentException
+     *             if the length of {@code value} is 0 but the size of {@code
+     *             attributes} is greater than 0.
+     * @throws NullPointerException
+     *             if {@code value} is {@code null}.
+     */
     public AttributedString(String value,
             Map<? extends AttributedCharacterIterator.Attribute, ?> attributes) {
         if (value == null) {
@@ -531,6 +563,19 @@
         }
     }
 
+    /**
+     * Applies a given attribute to this string.
+     *
+     * @param attribute
+     *            the attribute that will be applied to this string.
+     * @param value
+     *            the value of the attribute that will be applied to this
+     *            string.
+     * @throws IllegalArgumentException
+     *             if the length of this attributed string is 0.
+     * @throws NullPointerException
+     *             if {@code attribute} is {@code null}.
+     */
     public void addAttribute(AttributedCharacterIterator.Attribute attribute,
             Object value) {
         if (null == attribute) {
@@ -550,6 +595,24 @@
         ranges.add(new Range(0, text.length(), value));
     }
 
+    /**
+     * Applies a given attribute to the given range of this string.
+     *
+     * @param attribute
+     *            the attribute that will be applied to this string.
+     * @param value
+     *            the value of the attribute that will be applied to this
+     *            string.
+     * @param start
+     *            the start of the range where the attribute will be applied.
+     * @param end
+     *            the end of the range where the attribute will be applied.
+     * @throws IllegalArgumentException
+     *             if {@code start < 0}, {@code end} is greater than the length
+     *             of this string, or if {@code start >= end}.
+     * @throws NullPointerException
+     *             if {@code attribute} is {@code null}.
+     */
     public void addAttribute(AttributedCharacterIterator.Attribute attribute,
             Object value, int start, int end) {
         if (null == attribute) {
@@ -631,6 +694,19 @@
         it.add(new Range(start, end, value));
     }
 
+    /**
+     * Applies a given set of attributes to the given range of the string.
+     *
+     * @param attributes
+     *            the set of attributes that will be applied to this string.
+     * @param start
+     *            the start of the range where the attribute will be applied.
+     * @param end
+     *            the end of the range where the attribute will be applied.
+     * @throws IllegalArgumentException
+     *             if {@code start < 0}, {@code end} is greater than the length
+     *             of this string, or if {@code start >= end}.
+     */
     public void addAttributes(
             Map<? extends AttributedCharacterIterator.Attribute, ?> attributes,
             int start, int end) {
@@ -643,15 +719,47 @@
         }
     }
 
+    /**
+     * Returns an {@code AttributedCharacterIterator} that gives access to the
+     * complete content of this attributed string.
+     *
+     * @return the newly created {@code AttributedCharacterIterator}.
+     */
     public AttributedCharacterIterator getIterator() {
         return new AttributedIterator(this);
     }
 
+    /**
+     * Returns an {@code AttributedCharacterIterator} that gives access to the
+     * complete content of this attributed string. Only attributes contained in
+     * {@code attributes} are available from this iterator if they are defined
+     * for this text.
+     *
+     * @param attributes
+     *            the array containing attributes that will be in the new
+     *            iterator if they are defined for this text.
+     * @return the newly created {@code AttributedCharacterIterator}.
+     */
     public AttributedCharacterIterator getIterator(
             AttributedCharacterIterator.Attribute[] attributes) {
         return new AttributedIterator(this, attributes, 0, text.length());
     }
 
+    /**
+     * Returns an {@code AttributedCharacterIterator} that gives access to the
+     * contents of this attributed string starting at index {@code start} up to
+     * index {@code end}. Only attributes contained in {@code attributes} are
+     * available from this iterator if they are defined for this text.
+     *
+     * @param attributes
+     *            the array containing attributes that will be in the new
+     *            iterator if they are defined for this text.
+     * @param start
+     *            the start index of the iterator on the underlying text.
+     * @param end
+     *            the end index of the iterator on the underlying text.
+     * @return the newly created {@code AttributedCharacterIterator}.
+     */
     public AttributedCharacterIterator getIterator(
             AttributedCharacterIterator.Attribute[] attributes, int start,
             int end) {

Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/Bidi.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/Bidi.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/Bidi.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/Bidi.java Thu May  7 08:42:00 2009
@@ -20,11 +20,11 @@
 import org.apache.harmony.text.internal.nls.Messages;
 
 /**
- * Bidi is the class providing the bidirectional algorithm. The algorithm is
+ * Provides the Unicode Bidirectional Algorithm. The algorithm is
  * defined in the Unicode Standard Annex #9, version 13, also described in The
  * Unicode Standard, Version 4.0 .
  * 
- * Use a Bidi object to get the information on the position reordering of a
+ * Use a {@code Bidi} object to get the information on the position reordering of a
  * bidirectional text, such as Arabic or Hebrew. The natural display ordering of
  * horizontal text in these languages is from right to left, while they order
  * numbers from left to right.
@@ -37,25 +37,24 @@
 public final class Bidi {
     /**
      * Constant that indicates the default base level. If there is no strong
-     * character, then set the paragraph level to left-to-right.
+     * character, then set the paragraph level to 0 (left-to-right).
      */
     public static final int DIRECTION_DEFAULT_LEFT_TO_RIGHT = -2;
 
     /**
      * Constant that indicates the default base level. If there is no strong
-     * character, then set the paragraph level to right-to-left.
+     * character, then set the paragraph level to 1 (right-to-left).
      */
     public static final int DIRECTION_DEFAULT_RIGHT_TO_LEFT = -1;
 
     /**
-     * Constant that specifies the default base level as 
-     * left-to-right. 
+     * Constant that specifies the default base level as 0 (left-to-right).
      */
     public static final int DIRECTION_LEFT_TO_RIGHT = 0;
 
     /**
-     * Constant that specifies the default base level right-to-left.
-     */  
+     * Constant that specifies the default base level as 1 (right-to-left).
+     */
     public static final int DIRECTION_RIGHT_TO_LEFT = 1;
 
     /*
@@ -78,27 +77,26 @@
     private com.ibm.icu.text.Bidi icuBidi;
 
     /**
-     * Create a Bidi object from the AttributedCharacterIterator of a paragraph
-     * text.
-     * 
-     * The RUN_DIRECTION attribute determines the base direction of the
-     * bidirectional text. If it's not specified explicitly, the algorithm uses
-     * DIRECTION_DEFAULT_LEFT_TO_RIGHT by default.
-     * 
-     * The BIDI_EMBEDDING attribute specifies the level of embedding for each
-     * character. Values between -1 and -62 denote overrides at the level's
-     * absolute value, values from 1 to 62 indicate embeddings, and the 0 value
-     * indicates the level is calculated by the algorithm automatically. For the
-     * character with no BIDI_EMBEDDING attribute or with a improper attribute
-     * value, such as a null value, the algorithm treats its embedding level as
-     * 0.
-     * 
-     * The NUMERIC_SHAPING attribute specifies the instance of NumericShaper
-     * used to convert European digits to other decimal digits before performing
-     * the bidi algorithm.
-     * 
+     * Creates a {@code Bidi} object from the {@code
+     * AttributedCharacterIterator} of a paragraph text. The RUN_DIRECTION
+     * attribute determines the base direction of the bidirectional text. If it
+     * is not specified explicitly, the algorithm uses
+     * DIRECTION_DEFAULT_LEFT_TO_RIGHT by default. The BIDI_EMBEDDING attribute
+     * specifies the level of embedding for each character. Values between -1
+     * and -62 denote overrides at the level's absolute value, values from 1 to
+     * 62 indicate embeddings, and the 0 value indicates the level is calculated
+     * by the algorithm automatically. For the character with no BIDI_EMBEDDING
+     * attribute or with a improper attribute value, such as a {@code null}
+     * value, the algorithm treats its embedding level as 0. The NUMERIC_SHAPING
+     * attribute specifies the instance of NumericShaper used to convert
+     * European digits to other decimal digits before performing the bidi
+     * algorithm.
+     *
      * @param paragraph
-     * 
+     *            the String containing the paragraph text to perform the
+     *            algorithm.
+     * @throws IllegalArgumentException
+     *             if {@code paragraph} is {@code null}.
      * @see java.awt.font.TextAttribute#BIDI_EMBEDDING
      * @see java.awt.font.TextAttribute#NUMERIC_SHAPING
      * @see java.awt.font.TextAttribute#RUN_DIRECTION
@@ -113,32 +111,33 @@
     }
 
     /**
-     * Create a Bidi object.
+     * Creates a {@code Bidi} object.
      * 
      * @param text
-     *            the char array of the paragraph text.
+     *            the char array of the paragraph text that is processed.
      * @param textStart
-     *            the start offset of the text array to perform the algorithm.
+     *            the index in {@code text} of the start of the paragraph.
      * @param embeddings
      *            the embedding level array of the paragraph text, specifying
      *            the embedding level information for each character. Values
-     *            between -1 and -62 denote overrides at the level's absolute
-     *            value, values from 1 to 62 indicate embeddings, and the 0
+     *            between -1 and -61 denote overrides at the level's absolute
+     *            value, values from 1 to 61 indicate embeddings, and the 0
      *            value indicates the level is calculated by the algorithm
      *            automatically.
      * @param embStart
-     *            the start offset of the embeddings array to perform the
-     *            algorithm.
+     *            the index in {@code embeddings} of the start of the paragraph.
      * @param paragraphLength
-     *            the length of the text to perform the algorithm. It must be
-     *            text.length >= textStart + paragraphLength, and
-     *            embeddings.length >= embStart + paragraphLength.
+     *            the length of the text to perform the algorithm.
      * @param flags
      *            indicates the base direction of the bidirectional text. It is
      *            expected that this will be one of the direction constant
      *            values defined in this class. An unknown value is treated as
      *            DIRECTION_DEFAULT_LEFT_TO_RIGHT.
-     * 
+     * @throws IllegalArgumentException
+     *             if {@code textStart}, {@code embStart}, or {@code
+     *             paragraphLength} is negative; if
+     *             {@code text.length < textStart + paragraphLength} or
+     *             {@code embeddings.length < embStart + paragraphLength}.
      * @see #DIRECTION_LEFT_TO_RIGHT
      * @see #DIRECTION_RIGHT_TO_LEFT
      * @see #DIRECTION_DEFAULT_RIGHT_TO_LEFT
@@ -178,17 +177,16 @@
     }
 
     /**
-     * Create a Bidi object.
+     * Creates a {@code Bidi} object.
      * 
      * @param paragraph
-     *            the String containing the paragraph text to perform the
-     *            algorithm.
+     *            the string containing the paragraph text to perform the
+     *            algorithm on.
      * @param flags
      *            indicates the base direction of the bidirectional text. It is
      *            expected that this will be one of the direction constant
      *            values defined in this class. An unknown value is treated as
      *            DIRECTION_DEFAULT_LEFT_TO_RIGHT.
-     * 
      * @see #DIRECTION_LEFT_TO_RIGHT
      * @see #DIRECTION_RIGHT_TO_LEFT
      * @see #DIRECTION_DEFAULT_RIGHT_TO_LEFT
@@ -205,7 +203,7 @@
     }
 
     /**
-     * Return whether the base level is from left to right.
+     * Returns whether the base level is from left to right.
      * 
      * @return true if the base level is from left to right.
      */
@@ -214,8 +212,8 @@
     }
 
     /**
-     * Create a new Bidi object containing the information of one line from this
-     * object.
+     * Creates a new {@code Bidi} object containing the information of one line
+     * from this object.
      * 
      * @param lineStart
      *            the start offset of the line.
@@ -223,6 +221,10 @@
      *            the limit of the line.
      * @return the new line Bidi object. In this new object, the indices will
      *         range from 0 to (limit - start - 1).
+     * @throws IllegalArgumentException
+     *             if {@code lineStart < 0}, {@code lineLimit < 0}, {@code
+     *             lineStart > lineLimit} or if {@code lineStart} is greater
+     *             than the length of this object's paragraph text.
      */
     public Bidi createLineBidi(int lineStart, int lineLimit) {
         int length = icuBidi.getLength();
@@ -239,29 +241,29 @@
     }
 
     /**
-     * Return the base level.
+     * Returns the base level.
      * 
-     * @return the int value of the base level.
+     * @return the base level.
      */
     public int getBaseLevel() {
         return icuBidi.getBaseLevel();
     }
 
     /**
-     * Return the length of the text in the Bidi object.
+     * Returns the length of the text in the {@code Bidi} object.
      * 
-     * @return the int value of the length.
+     * @return the length.
      */
     public int getLength() {
         return icuBidi.getLength();
     }
 
     /**
-     * Return the level of a specified character.
+     * Returns the level of a specified character.
      * 
      * @param offset
      *            the offset of the character.
-     * @return the int value of the level.
+     * @return the level.
      */
     public int getLevelAt(int offset) {
         try {
@@ -272,9 +274,9 @@
     }
 
     /**
-     * Return the number of runs in the bidirectional text.
+     * Returns the number of runs in the bidirectional text.
      * 
-     * @return the int value of runs, at least 1.
+     * @return the number of runs, at least 1.
      */
     public int getRunCount() {
         int runCount = icuBidi.getRunCount();
@@ -282,7 +284,7 @@
     }
 
     /**
-     * Return the level of a specified run.
+     * Returns the level of the specified run.
      * 
      * @param run
      *            the index of the run.
@@ -297,7 +299,7 @@
     }
 
     /**
-     * Return the limit offset of a specified run.
+     * Returns the limit offset of the specified run.
      * 
      * @param run
      *            the index of the run.
@@ -312,7 +314,7 @@
     }
 
     /**
-     * Return the start offset of a specified run.
+     * Returns the start offset of the specified run.
      * 
      * @param run
      *            the index of the run.
@@ -327,40 +329,43 @@
     }
 
     /**
-     * Return whether the text is from left to right, that is, both the base
+     * Indicates whether the text is from left to right, that is, both the base
      * direction and the text direction is from left to right.
      * 
-     * @return true if the text is from left to right.
+     * @return {@code true} if the text is from left to right; {@code false}
+     *         otherwise.
      */
     public boolean isLeftToRight() {
         return icuBidi.isLeftToRight();
     }
 
     /**
-     * Return whether the text direction is mixed.
+     * Indicates whether the text direction is mixed.
      * 
-     * @return true if the text direction is mixed.
+     * @return {@code true} if the text direction is mixed; {@code false}
+     *         otherwise.
      */
     public boolean isMixed() {
         return icuBidi.isMixed();
     }
 
     /**
-     * Return whether the text is from right to left, that is, both the base
+     * Indicates whether the text is from right to left, that is, both the base
      * direction and the text direction is from right to left.
      * 
-     * @return true if the text is from right to left.
+     * @return {@code true} if the text is from right to left; {@code false}
+     *         otherwise.
      */
     public boolean isRightToLeft() {
         return icuBidi.isRightToLeft();
     }
 
     /**
-     * Reorder a range of objects according to their specified levels. This is a
-     * convenience function that does not use a Bidi object. The range of
-     * objects at index from objectStart to objectStart + count will be
-     * reordered according to the range of levels at index from levelStart to
-     * levelStart + count.
+     * Reorders a range of objects according to their specified levels. This is
+     * a convenience function that does not use a {@code Bidi} object. The range
+     * of objects at {@code index} from {@code objectStart} to {@code
+     * objectStart + count} will be reordered according to the range of levels
+     * at {@code index} from {@code levelStart} to {@code levelStart + count}.
      * 
      * @param levels
      *            the level array, which is already determined.
@@ -372,6 +377,10 @@
      *            the start offset of the range of objects.
      * @param count
      *            the count of the range of objects to reorder.
+     * @throws IllegalArgumentException
+     *             if {@code count}, {@code levelStart} or {@code objectStart}
+     *             is negative; if {@code count > levels.length - levelStart} or
+     *             if {@code count > objects.length - objectStart}.
      */
     public static void reorderVisually(byte[] levels, int levelStart,
             Object[] objects, int objectStart, int count) {
@@ -389,8 +398,8 @@
     }
 
     /**
-     * Return whether a range of characters of a text requires a Bidi object to
-     * display properly.
+     * Indicates whether a range of characters of a text requires a {@code Bidi}
+     * object to display properly.
      * 
      * @param text
      *            the char array of the text.
@@ -398,7 +407,12 @@
      *            the start offset of the range of characters.
      * @param limit
      *            the limit offset of the range of characters.
-     * @return true if the range of characters requires a Bidi object.
+     * @return {@code true} if the range of characters requires a {@code Bidi}
+     *         object; {@code false} otherwise.
+     * @throws IllegalArgumentException
+     *             if {@code start} or {@code limit} is negative; {@code start >
+     *             limit} or {@code limit} is greater than the length of this
+     *             object's paragraph text.
      */
     public static boolean requiresBidi(char[] text, int start, int limit) {
         //int length = text.length;
@@ -410,7 +424,8 @@
     }
 
     /**
-     * Return the internal message of the Bidi object, used in debugging.
+     * Returns the internal message of the {@code Bidi} object, used in
+     * debugging.
      * 
      * @return a string containing the internal message.
      */

Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/BreakIterator.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/BreakIterator.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/BreakIterator.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/BreakIterator.java Thu May  7 08:42:00 2009
@@ -20,32 +20,204 @@
 import java.util.Locale;
 
 /**
- * This class is used to locate the boundaries of text. Instance of this class
- * can be got by some factory methods:
+ * Locates boundaries in text. This class defines a protocol for objects that
+ * break up a piece of natural-language text according to a set of criteria.
+ * Instances or subclasses of {@code BreakIterator} can be provided, for
+ * example, to break a piece of text into words, sentences, or logical
+ * characters according to the conventions of some language or group of
+ * languages. We provide four built-in types of {@code BreakIterator}:
  * <ul>
- * <li>
- * <code>getCharacterInstance()<code> returns a BreakIterator that iterate the 
- * logical characters without worrying about how the character is stored. For 
- * example, some character may be stored in more than one Unicode code point 
- * according to Unicode specification, this character can handle the logical 
- * characters with multi code points.</li>
- * <li>
- * <code>getWordInstance()<code> returns a <code>BreakIterator</code> that 
- * iterate the word-breaks. The beginning and end of each word(including numbers) 
- * is treated as boundary position. Whitespace and punctuation are kept separate 
- * from real words.</li>
- * <li>
- * <code>getSentenceInstance()</code> returns a BreakIterator that iterate the 
- * sentence-breaks.</li>
- * <li><code>getLineInstance()</code> returns a BreakIterator that iterate the 
- * line-breaks which can be used to wrap lines. This iterator can handle whitespaces, 
- * hyphens and punctuations.  
+ * <li>{@link #getSentenceInstance()} returns a {@code BreakIterator} that
+ * locates boundaries between sentences. This is useful for triple-click
+ * selection, for example.</li>
+ * <li>{@link #getWordInstance()} returns a {@code BreakIterator} that locates
+ * boundaries between words. This is useful for double-click selection or "find
+ * whole words" searches. This type of {@code BreakIterator} makes sure there is
+ * a boundary position at the beginning and end of each legal word (numbers
+ * count as words, too). Whitespace and punctuation are kept separate from real
+ * words.</li>
+ * <li>{@code getLineInstance()} returns a {@code BreakIterator} that locates
+ * positions where it is legal for a text editor to wrap lines. This is similar
+ * to word breaking, but not the same: punctuation and whitespace are generally
+ * kept with words (you don't want a line to start with whitespace, for
+ * example), and some special characters can force a position to be considered a
+ * line break position or prevent a position from being a line break position.</li>
+ * <li>{@code getCharacterInstance()} returns a {@code BreakIterator} that
+ * locates boundaries between logical characters. Because of the structure of
+ * the Unicode encoding, a logical character may be stored internally as more
+ * than one Unicode code point. (A with an umlaut may be stored as an a followed
+ * by a separate combining umlaut character, for example, but the user still
+ * thinks of it as one character.) This iterator allows various processes
+ * (especially text editors) to treat as characters the units of text that a
+ * user would think of as characters, rather than the units of text that the
+ * computer sees as "characters".</li>
+ * </ul> {@code BreakIterator}'s interface follows an "iterator" model (hence
+ * the name), meaning it has a concept of a "current position" and methods like
+ * {@code first()}, {@code last()}, {@code next()}, and {@code previous()} that
+ * update the current position. All {@code BreakIterator}s uphold the following
+ * invariants:
+ * <ul>
+ * <li>The beginning and end of the text are always treated as boundary
+ * positions.</li>
+ * <li>The current position of the iterator is always a boundary position
+ * (random- access methods move the iterator to the nearest boundary position
+ * before or after the specified position, not <i>to</i> the specified
+ * position).</li>
+ * <li>{@code DONE} is used as a flag to indicate when iteration has stopped.
+ * {@code DONE} is only returned when the current position is the end of the
+ * text and the user calls {@code next()}, or when the current position is the
+ * beginning of the text and the user calls {@code previous()}.</li>
+ * <li>Break positions are numbered by the positions of the characters that
+ * follow them. Thus, under normal circumstances, the position before the first
+ * character is 0, the position after the first character is 1, and the position
+ * after the last character is 1 plus the length of the string.</li>
+ * <li>The client can change the position of an iterator, or the text it
+ * analyzes, at will, but cannot change the behavior. If the user wants
+ * different behavior, he must instantiate a new iterator.</li>
  * </ul>
- * 
- * <code>BreakIterator</code> uses <code>CharacterIterator</code> to perform the 
- * analysis, so that any storage which provides <code>CharacterIterator</code> 
- * interface.
- * 
+ * <p>
+ * {@code BreakIterator} accesses the text it analyzes through a
+ * {@link CharacterIterator}, which makes it possible to use {@code
+ * BreakIterator} to analyze text in any text-storage vehicle that provides a
+ * {@code CharacterIterator} interface.
+ * <p>
+ * <em>Note:</em> Some types of {@code BreakIterator} can take a long time to
+ * create, and instances of {@code BreakIterator} are not currently cached by
+ * the system. For optimal performance, keep instances of {@code BreakIterator}
+ * around as long as it makes sense. For example, when word-wrapping a document,
+ * don't create and destroy a new {@code BreakIterator} for each line. Create
+ * one break iterator for the whole document (or whatever stretch of text you're
+ * wrapping) and use it to do the whole job of wrapping the text.
+ * <p>
+ * <em>Examples</em>:
+ * <p>
+ * Creating and using text boundaries:
+ * <blockquote>
+ *
+ * <pre>
+ * public static void main(String args[]) {
+ *     if (args.length == 1) {
+ *         String stringToExamine = args[0];
+ *         //print each word in order
+ *         BreakIterator boundary = BreakIterator.getWordInstance();
+ *         boundary.setText(stringToExamine);
+ *         printEachForward(boundary, stringToExamine);
+ *         //print each sentence in reverse order
+ *         boundary = BreakIterator.getSentenceInstance(Locale.US);
+ *         boundary.setText(stringToExamine);
+ *         printEachBackward(boundary, stringToExamine);
+ *         printFirst(boundary, stringToExamine);
+ *         printLast(boundary, stringToExamine);
+ *     }
+ * }
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * Print each element in order:
+ * <blockquote>
+ *
+ * <pre>
+ * public static void printEachForward(BreakIterator boundary, String source) {
+ *     int start = boundary.first();
+ *     for (int end = boundary.next(); end != BreakIterator.DONE; start = end, end = boundary.next()) {
+ *         System.out.println(source.substring(start, end));
+ *     }
+ * }
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * Print each element in reverse order:
+ * <blockquote>
+ *
+ * <pre>
+ * public static void printEachBackward(BreakIterator boundary, String source) {
+ *     int end = boundary.last();
+ *     for (int start = boundary.previous(); start != BreakIterator.DONE; end = start, start = boundary
+ *             .previous()) {
+ *         System.out.println(source.substring(start, end));
+ *     }
+ * }
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * Print the first element:
+ * <blockquote>
+ *
+ * <pre>
+ * public static void printFirst(BreakIterator boundary, String source) {
+ *     int start = boundary.first();
+ *     int end = boundary.next();
+ *     System.out.println(source.substring(start, end));
+ * }
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * Print the last element:
+ * <blockquote>
+ *
+ * <pre>
+ * public static void printLast(BreakIterator boundary, String source) {
+ *     int end = boundary.last();
+ *     int start = boundary.previous();
+ *     System.out.println(source.substring(start, end));
+ * }
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * Print the element at a specified position:
+ * <blockquote>
+ *
+ * <pre>
+ * public static void printAt(BreakIterator boundary, int pos, String source) {
+ *     int end = boundary.following(pos);
+ *     int start = boundary.previous();
+ *     System.out.println(source.substring(start, end));
+ * }
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * Find the next word:
+ * <blockquote>
+ *
+ * <pre>
+ * public static int nextWordStartAfter(int pos, String text) {
+ *     BreakIterator wb = BreakIterator.getWordInstance();
+ *     wb.setText(text);
+ *     int last = wb.following(pos);
+ *     int current = wb.next();
+ *     while (current != BreakIterator.DONE) {
+ *         for (int p = last; p &lt; current; p++) {
+ *             if (Character.isLetter(text.charAt(p)))
+ *                 return last;
+ *         }
+ *         last = current;
+ *         current = wb.next();
+ *     }
+ *     return BreakIterator.DONE;
+ * }
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * The iterator returned by {@code BreakIterator.getWordInstance()} is unique in
+ * that the break positions it returns don't represent both the start and end of
+ * the thing being iterated over. That is, a sentence-break iterator returns
+ * breaks that each represent the end of one sentence and the beginning of the
+ * next. With the word-break iterator, the characters between two boundaries
+ * might be a word, or they might be the punctuation or whitespace between two
+ * words. The above code uses a simple heuristic to determine which boundary is
+ * the beginning of a word: If the characters between this boundary and the next
+ * boundary include at least one letter (this can be an alphabetical letter, a
+ * CJK ideograph, a Hangul syllable, a Kana character, etc.), then the text
+ * between this boundary and the next is a word; otherwise, it's the material
+ * between words.)
+ *
  * @see CharacterIterator
  */
 public abstract class BreakIterator implements Cloneable {
@@ -56,8 +228,8 @@
      * -----------------------------------------------------------------------
      */
     /**
-     * This constant is returned by iterate methods like previous() or next() if
-     * they have returned all valid boundaries.
+     * This constant is returned by iterate methods like {@code previous()} or
+     * {@code next()} if they have returned all valid boundaries.
      */
     public static final int DONE = -1;
 
@@ -100,20 +272,19 @@
      * -----------------------------------------------------------------------
      */
     /**
-     * Return all supported locales.
+     * Returns all supported locales in an array.
      * 
-     * @return all supported locales
+     * @return all supported locales.
      */
     public static Locale[] getAvailableLocales() {
         return com.ibm.icu.text.BreakIterator.getAvailableLocales();
     }
 
     /**
-     * Return a new instance of BreakIterator used to iterate characters using
-     * default locale.
+     * Returns a new instance of {@code BreakIterator} to iterate over
+     * characters using the default locale.
      * 
-     * @return a new instance of BreakIterator used to iterate characters using
-     *         default locale.
+     * @return a new instance of {@code BreakIterator} using the default locale.
      */
     public static BreakIterator getCharacterInstance() {
         return new RuleBasedBreakIterator(com.ibm.icu.text.BreakIterator
@@ -121,13 +292,12 @@
     }
 
     /**
-     * Return a new instance of BreakIterator used to iterate characters using
-     * given locale.
+     * Returns a new instance of {@code BreakIterator} to iterate over
+     * characters using the given locale.
      * 
      * @param where
-     *            the given locale
-     * @return a new instance of BreakIterator used to iterate characters using
-     *         given locale.
+     *            the given locale.
+     * @return a new instance of {@code BreakIterator} using the given locale.
      */
     public static BreakIterator getCharacterInstance(Locale where) {
         if (where == null) {
@@ -139,11 +309,10 @@
     }
 
     /**
-     * Return a new instance of BreakIterator used to iterate line-breaks using
-     * default locale.
+     * Returns a new instance of {{@code BreakIterator} to iterate over
+     * line breaks using the default locale.
      * 
-     * @return a new instance of BreakIterator used to iterate line-breaks using
-     *         default locale.
+     * @return a new instance of {@code BreakIterator} using the default locale.
      */
     public static BreakIterator getLineInstance() {
         return new RuleBasedBreakIterator(com.ibm.icu.text.BreakIterator
@@ -151,13 +320,13 @@
     }
 
     /**
-     * Return a new instance of BreakIterator used to iterate line-breaks using
-     * given locale.
+     * Returns a new instance of {@code BreakIterator} to iterate over
+     * line breaks using the given locale.
      * 
      * @param where
-     *            the given locale
-     * @return a new instance of BreakIterator used to iterate line-breaks using
-     *         given locale.
+     *            the given locale.
+     * @return a new instance of {@code BreakIterator} using the given locale.
+     * @throws NullPointerException if {@code where} is {@code null}.
      */
     public static BreakIterator getLineInstance(Locale where) {
         if (where == null) {
@@ -169,11 +338,10 @@
     }
 
     /**
-     * Return a new instance of BreakIterator used to iterate sentence-breaks
-     * using default locale.
+     * Returns a new instance of {@code BreakIterator} to iterate over
+     * sentence-breaks using the default locale.
      * 
-     * @return a new instance of BreakIterator used to iterate sentence-breaks
-     *         using default locale.
+     * @return a new instance of {@code BreakIterator} using the default locale.
      */
     public static BreakIterator getSentenceInstance() {
         return new RuleBasedBreakIterator(com.ibm.icu.text.BreakIterator
@@ -181,13 +349,13 @@
     }
 
     /**
-     * Return a new instance of BreakIterator used to iterate sentence-breaks
-     * using given locale.
+     * Returns a new instance of {@code BreakIterator} to iterate over
+     * sentence-breaks using the given locale.
      * 
      * @param where
-     *            the given locale
-     * @return a new instance of BreakIterator used to iterate sentence-breaks
-     *         using given locale.
+     *            the given locale.
+     * @return a new instance of {@code BreakIterator} using the given locale.
+     * @throws NullPointerException if {@code where} is {@code null}.
      */
     public static BreakIterator getSentenceInstance(Locale where) {
         if (where == null) {
@@ -199,11 +367,10 @@
     }
 
     /**
-     * Return a new instance of BreakIterator used to iterate word-breaks using
-     * default locale.
+     * Returns a new instance of {@code BreakIterator} to iterate over
+     * word-breaks using the default locale.
      * 
-     * @return a new instance of BreakIterator used to iterate word-breaks using
-     *         default locale.
+     * @return a new instance of {@code BreakIterator} using the default locale.
      */
     public static BreakIterator getWordInstance() {
         return new RuleBasedBreakIterator(com.ibm.icu.text.BreakIterator
@@ -211,13 +378,13 @@
     }
 
     /**
-     * Return a new instance of BreakIterator used to iterate word-breaks using
-     * given locale.
+     * Returns a new instance of {@code BreakIterator} to iterate over
+     * word-breaks using the given locale.
      * 
      * @param where
-     *            the given locale
-     * @return a new instance of BreakIterator used to iterate word-breaks using
-     *         given locale.
+     *            the given locale.
+     * @return a new instance of {@code BreakIterator} using the given locale.
+     * @throws NullPointerException if {@code where} is {@code null}.
      */
     public static BreakIterator getWordInstance(Locale where) {
         if (where == null) {
@@ -229,42 +396,42 @@
     }
 
     /**
-     * Return true if the given offset is a boundary position. If this method
+     * Indicates whether the given offset is a boundary position. If this method
      * returns true, the current iteration position is set to the given
      * position; if the function returns false, the current iteration position
-     * is set as though following() had been called.
+     * is set as though {@link #following(int)} had been called.
      * 
      * @param offset
-     *            the given offset to check
-     * @return true if the given offset is a boundary position
+     *            the given offset to check.
+     * @return {@code true} if the given offset is a boundary position; {@code
+     *         false} otherwise.
      */
     public boolean isBoundary(int offset) {
         return wrapped.isBoundary(offset);
     }
 
     /**
-     * Return the position of last boundary precede the given offset, and set
-     * current position to returned value, or <code>DONE</code> if the given
-     * offset specifies the starting position.
-     * <p>
-     * <code>IllegalArgumentException</code> will be thrown if given offset is
-     * invalid.
-     * </p>
-     * 
+     * Returns the position of last boundary preceding the given offset, and
+     * sets the current position to the returned value, or {@code DONE} if the
+     * given offset specifies the starting position.
+     *
      * @param offset
-     *            the given start position to be searched for
-     * @return the position of last boundary precede the given offset
+     *            the given start position to be searched for.
+     * @return the position of the last boundary preceding the given offset.
+     * @throws IllegalArgumentException
+     *            if the offset is invalid.
      */
     public int preceding(int offset) {
         return wrapped.preceding(offset);
     }
 
     /**
-     * Set the new text string to be analyzed, the current position will be
-     * reset to beginning of this new string, and the old string will lost.
+     * Sets the new text string to be analyzed, the current position will be
+     * reset to the beginning of this new string, and the old string will be
+     * lost.
      * 
      * @param newText
-     *            the new text string to be analyzed
+     *            the new text string to be analyzed.
      */
     public void setText(String newText) {
         wrapped.setText(newText);
@@ -276,92 +443,90 @@
      * -----------------------------------------------------------------------
      */
     /**
-     * Return this iterator's current position.
+     * Returns this iterator's current position.
      * 
-     * @return this iterator's current position
+     * @return this iterator's current position.
      */
     public abstract int current();
 
     /**
-     * Set this iterator's current position to the first boundary, and return
-     * this position.
+     * Sets this iterator's current position to the first boundary and returns
+     * that position.
      * 
-     * @return the position of first boundary
+     * @return the position of the first boundary.
      */
     public abstract int first();
 
     /**
-     * Set the position of the first boundary following the given offset, and
-     * return this position. If there is no boundary after the given offset,
-     * return DONE.
-     * <p>
-     * <code>IllegalArgumentException</code> will be thrown if given offset is
-     * invalid.
-     * </p>
-     * 
+     * Sets the position of the first boundary to the one following the given
+     * offset and returns this position. Returns {@code DONE} if there is no
+     * boundary after the given offset.
+     *
      * @param offset
-     *            the given position to be searched for
-     * @return the position of the first boundary following the given offset
+     *            the given position to be searched for.
+     * @return the position of the first boundary following the given offset.
+     * @throws IllegalArgumentException
+     *            if the offset is invalid.
      */
     public abstract int following(int offset);
 
     /**
-     * Return a <code>CharacterIterator</code> which represents the text being
+     * Returns a {@code CharacterIterator} which represents the text being
      * analyzed. Please note that the returned value is probably the internal
-     * iterator used by this object, so that if the invoker want to modify the
-     * status of the returned iterator, a clone operation at first is
-     * recommended.
+     * iterator used by this object. If the invoker wants to modify the status
+     * of the returned iterator, it is recommended to first create a clone of
+     * the iterator returned.
      * 
-     * @return a <code>CharacterIterator</code> which represents the text
-     *         being analyzed.
+     * @return a {@code CharacterIterator} which represents the text being
+     *         analyzed.
      */
     public abstract CharacterIterator getText();
 
     /**
-     * Set this iterator's current position to the last boundary, and return
-     * this position.
+     * Sets this iterator's current position to the last boundary and returns
+     * that position.
      * 
-     * @return the position of last boundary
+     * @return the position of last boundary.
      */
     public abstract int last();
 
     /**
-     * Set this iterator's current position to the next boundary after current
-     * position, and return this position. Return <code>DONE</code> if no
-     * boundary found after current position.
+     * Sets this iterator's current position to the next boundary after the
+     * current position, and returns this position. Returns {@code DONE} if no
+     * boundary was found after the current position.
      * 
-     * @return the position of last boundary
+     * @return the position of last boundary.
      */
     public abstract int next();
 
     /**
-     * Set this iterator's current position to the next boundary after the given
-     * position, and return this position. Return <code>DONE</code> if no
-     * boundary found after the given position.
+     * Sets this iterator's current position to the next boundary after the
+     * given position, and returns that position. Returns {@code DONE} if no
+     * boundary was found after the given position.
      * 
      * @param n
      *            the given position.
-     * @return the position of last boundary
+     * @return the position of last boundary.
      */
     public abstract int next(int n);
 
     /**
-     * Set this iterator's current position to the previous boundary before
-     * current position, and return this position. Return <code>DONE</code> if
-     * no boundary found before current position.
+     * Sets this iterator's current position to the previous boundary before the
+     * current position and returns that position. Returns {@code DONE} if
+     * no boundary was found before the current position.
      * 
-     * @return the position of last boundary
+     * @return the position of last boundary.
      */
     public abstract int previous();
 
     /**
-     * Set new text to be analyzed by given <code>CharacterIterator</code>.
+     * Sets the new text to be analyzed by the given {@code CharacterIterator}.
      * The position will be reset to the beginning of the new text, and other
-     * status of this iterator will be kept.
+     * status information of this iterator will be kept.
      * 
      * @param newText
-     *            the given <code>CharacterIterator</code> refer to the text
-     *            to be analyzed
+     *            the {@code CharacterIterator} referring to the text to be
+     *            analyzed.
      */
     public abstract void setText(CharacterIterator newText);
 
@@ -371,10 +536,10 @@
      * -----------------------------------------------------------------------
      */
     /**
-     * Create copy of this iterator, all status including current position is
-     * kept.
+     * Creates a copy of this iterator, all status information including the
+     * current position are kept the same.
      * 
-     * @return copy of this iterator
+     * @return a copy of this iterator.
      */
     @Override
     public Object clone() {
@@ -388,13 +553,19 @@
     }
 
     /**
-     * Get a long value from the given byte array, start from given offset.
+     * Gets a long value from the given byte array, starting from the given
+     * offset.
      * 
      * @param buf
-     *            the bytes to be converted
+     *            the bytes to be converted.
      * @param offset
-     *            the start position of conversion
-     * @return the converted long value
+     *            the start position of the conversion.
+     * @return the converted long value.
+     * @throws NullPointerException
+     *             if {@code buf} is {@code null}.
+     * @throws ArrayIndexOutOfBoundsException
+     *             if {@code offset < 0} or {@code offset + LONG_LENGTH} is
+     *             greater than the length of {@code buf}.
      */
     protected static long getLong(byte[] buf, int offset) {
         if (null == buf) {
@@ -411,13 +582,19 @@
     }
 
     /**
-     * Get an int value from the given byte array, start from given offset.
+     * Gets an int value from the given byte array, starting from the given
+     * offset.
      * 
      * @param buf
-     *            the bytes to be converted
+     *            the bytes to be converted.
      * @param offset
-     *            the start position of conversion
-     * @return the converted int value
+     *            the start position of the conversion.
+     * @return the converted int value.
+     * @throws NullPointerException
+     *             if {@code buf} is {@code null}.
+     * @throws ArrayIndexOutOfBoundsException
+     *             if {@code offset < 0} or {@code offset + INT_LENGTH} is
+     *             greater than the length of {@code buf}.
      */
     protected static int getInt(byte[] buf, int offset) {
         if (null == buf) {
@@ -434,13 +611,19 @@
     }
 
     /**
-     * Get a short value from the given byte array, start from given offset.
+     * Gets a short value from the given byte array, starting from the given
+     * offset.
      * 
      * @param buf
-     *            the bytes to be converted
+     *            the bytes to be converted.
      * @param offset
-     *            the start position of conversion
-     * @return the converted short value
+     *            the start position of the conversion.
+     * @return the converted short value.
+     * @throws NullPointerException
+     *             if {@code buf} is {@code null}.
+     * @throws ArrayIndexOutOfBoundsException
+     *             if {@code offset < 0} or {@code offset + SHORT_LENGTH} is
+     *             greater than the length of {@code buf}.
      */
     protected static short getShort(byte[] buf, int offset) {
         if (null == buf) {

Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/CharacterIterator.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/CharacterIterator.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/CharacterIterator.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/CharacterIterator.java Thu May  7 08:42:00 2009
@@ -18,96 +18,99 @@
 package java.text;
 
 /**
- * CharacterIterator is used to sequence over a group of characters. The
- * iteration starts at the begin index in the group of character and continues
+ * An interface for the bidirectional iteration over a group of characters. The
+ * iteration starts at the begin index in the group of characters and continues
  * to one index before the end index.
  */
 public interface CharacterIterator extends Cloneable {
 
     /**
-     * A constant which indicates there is no character.
+     * A constant which indicates that there is no character at the current
+     * index.
      */
     public static final char DONE = '\uffff';
 
     /**
-     * Answers a new CharacterIterator with the same properties.
+     * Returns a new {@code CharacterIterator} with the same properties.
      * 
-     * @return a shallow copy of this CharacterIterator
+     * @return a shallow copy of this character iterator.
      * 
      * @see java.lang.Cloneable
      */
     public Object clone();
 
     /**
-     * Answers the character at the current index.
+     * Returns the character at the current index.
      * 
-     * @return the current character, or DONE if the current index is past the
-     *         end
+     * @return the current character, or {@code DONE} if the current index is
+     *         past the beginning or end of the sequence.
      */
     public char current();
 
     /**
-     * Sets the current position to the begin index and answers the character at
-     * the begin index.
+     * Sets the current position to the begin index and returns the character at
+     * the new position.
      * 
-     * @return the character at the begin index
+     * @return the character at the begin index.
      */
     public char first();
 
     /**
-     * Answers the begin index.
+     * Returns the begin index.
      * 
-     * @return the index of the first character to iterate
+     * @return the index of the first character of the iteration.
      */
     public int getBeginIndex();
 
     /**
-     * Answers the end index.
+     * Returns the end index.
      * 
-     * @return the index one past the last character to iterate
+     * @return the index one past the last character of the iteration.
      */
     public int getEndIndex();
 
     /**
-     * Answers the current index.
+     * Returns the current index.
      * 
-     * @return the current index
+     * @return the current index.
      */
     public int getIndex();
 
     /**
-     * Sets the current position to the end index - 1 and answers the character
-     * at the current position.
+     * Sets the current position to the end index - 1 and returns the character
+     * at the new position.
      * 
-     * @return the character before the end index
+     * @return the character before the end index.
      */
     public char last();
 
     /**
      * Increments the current index and returns the character at the new index.
      * 
-     * @return the character at the next index, or DONE if the next index is
-     *         past the end
+     * @return the character at the next index, or {@code DONE} if the next
+     *         index would be past the end.
      */
     public char next();
 
     /**
      * Decrements the current index and returns the character at the new index.
      * 
-     * @return the character at the previous index, or DONE if the previous
-     *         index is past the beginning
+     * @return the character at the previous index, or {@code DONE} if the
+     *         previous index would be past the beginning.
      */
     public char previous();
 
     /**
-     * Sets the current index.
+     * Sets the current index to a new position and returns the character at the
+     * new index.
      * 
-     * @return the character at the new index, or DONE if the index is past the
-     *         end
-     * 
-     * @exception IllegalArgumentException
-     *                when the new index is less than the begin index or greater
-     *                than the end index
+     * @param location
+     *            the new index that this character iterator is set to.
+     * @return the character at the new index, or {@code DONE} if the index is
+     *         past the end.
+     * @throws IllegalArgumentException
+     *         if {@code location} is less than the begin index or greater than
+     *         the end index.
      */
     public char setIndex(int location);
 }



Mime
View raw message