harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r769094 [1/2] - in /harmony/enhanced/classlib/trunk/modules/nio_char/src/main/java/java/nio/charset: ./ spi/
Date Mon, 27 Apr 2009 18:39:25 GMT
Author: tellison
Date: Mon Apr 27 18:39:23 2009
New Revision: 769094

URL: http://svn.apache.org/viewvc?rev=769094&view=rev
Log:
Apply patch for HARMONY-6182 (Javadocs for java.nio.charsest.*)

Modified:
    harmony/enhanced/classlib/trunk/modules/nio_char/src/main/java/java/nio/charset/CharacterCodingException.java
    harmony/enhanced/classlib/trunk/modules/nio_char/src/main/java/java/nio/charset/Charset.java
    harmony/enhanced/classlib/trunk/modules/nio_char/src/main/java/java/nio/charset/CharsetDecoder.java
    harmony/enhanced/classlib/trunk/modules/nio_char/src/main/java/java/nio/charset/CharsetEncoder.java
    harmony/enhanced/classlib/trunk/modules/nio_char/src/main/java/java/nio/charset/CoderMalfunctionError.java
    harmony/enhanced/classlib/trunk/modules/nio_char/src/main/java/java/nio/charset/CoderResult.java
    harmony/enhanced/classlib/trunk/modules/nio_char/src/main/java/java/nio/charset/CodingErrorAction.java
    harmony/enhanced/classlib/trunk/modules/nio_char/src/main/java/java/nio/charset/IllegalCharsetNameException.java
    harmony/enhanced/classlib/trunk/modules/nio_char/src/main/java/java/nio/charset/MalformedInputException.java
    harmony/enhanced/classlib/trunk/modules/nio_char/src/main/java/java/nio/charset/UnmappableCharacterException.java
    harmony/enhanced/classlib/trunk/modules/nio_char/src/main/java/java/nio/charset/UnsupportedCharsetException.java
    harmony/enhanced/classlib/trunk/modules/nio_char/src/main/java/java/nio/charset/spi/CharsetProvider.java

Modified: harmony/enhanced/classlib/trunk/modules/nio_char/src/main/java/java/nio/charset/CharacterCodingException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio_char/src/main/java/java/nio/charset/CharacterCodingException.java?rev=769094&r1=769093&r2=769094&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio_char/src/main/java/java/nio/charset/CharacterCodingException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio_char/src/main/java/java/nio/charset/CharacterCodingException.java Mon Apr 27 18:39:23 2009
@@ -20,9 +20,8 @@
 import java.io.IOException;
 
 /**
- * 
- * Type of exception thrown when an encoding or decoding error occurs.
- * 
+ * A {@code CharacterCodingException} is thrown when an encoding or decoding
+ * error occurs.
  */
 public class CharacterCodingException extends IOException {
 
@@ -33,7 +32,7 @@
     private static final long serialVersionUID = 8421532232154627783L;
 
     /**
-     * Default constructor.
+     * Constructs a new {@code CharacterCodingException}.
      */
     public CharacterCodingException() {
         super();

Modified: harmony/enhanced/classlib/trunk/modules/nio_char/src/main/java/java/nio/charset/Charset.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio_char/src/main/java/java/nio/charset/Charset.java?rev=769094&r1=769093&r2=769094&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio_char/src/main/java/java/nio/charset/Charset.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio_char/src/main/java/java/nio/charset/Charset.java Mon Apr 27 18:39:23 2009
@@ -43,36 +43,33 @@
 
 /**
  * A charset defines a mapping between a Unicode character sequence and a byte
- * sequence. It facilitate the encoding from a Unicode character sequence into a
- * byte sequence, and the decoding from a byte sequence into a Unicode character
- * sequence.
+ * sequence. It facilitates the encoding from a Unicode character sequence into
+ * a byte sequence, and the decoding from a byte sequence into a Unicode
+ * character sequence.
  * <p>
- * A charset has a canonical name, which are usually in uppercase. Typically it
+ * A charset has a canonical name, which is usually in uppercase. Typically it
  * also has one or more aliases. The name string can only consist of the
  * following characters: '0' - '9', 'A' - 'Z', 'a' - 'z', '.', ':'. '-' and '_'.
  * The first character of the name must be a digit or a letter.
- * </p>
  * <p>
- * The following charsets should be supported by any java platforms: US-ASCII,
+ * The following charsets should be supported by any java platform: US-ASCII,
  * ISO-8859-1, UTF-8, UTF-16BE, UTF-16LE, UTF-16.
- * </p>
  * <p>
  * Additional charsets can be made available by configuring one or more charset
  * providers through provider configuration files. Such files are always named
  * as "java.nio.charset.spi.CharsetProvider" and located in the
  * "META-INF/services" sub folder of one or more classpaths. The files should be
  * encoded in "UTF-8". Each line of their content specifies the class name of a
- * charset provider which extends <code>java.nio.spi.CharsetProvider</code>. A
- * line should ends with '\r', '\n' or '\r\n'. Leading and trailing whitespaces
- * are trimmed. Blank lines, and lines (after trimmed) starting with "#" which
- * are regarded as comments, are both ignored. Duplicates of already appeared
- * names are also ignored. Both the configuration files and the provider classes
- * will be loaded using the thread context class loader.
- * </p>
+ * charset provider which extends
+ * <code>java.nio.charset.spi.CharsetProvider</code>. A line should end with
+ * '\r', '\n' or '\r\n'. Leading and trailing whitespaces are trimmed. Blank
+ * lines, and lines (after trimming) starting with "#" which are regarded as
+ * comments, are both ignored. Duplicates of names already found are also
+ * ignored. Both the configuration files and the provider classes will be loaded
+ * using the thread context class loader.
  * <p>
  * This class is thread-safe.
- * </p>
- * 
+ *
  * @see java.nio.charset.spi.CharsetProvider
  */
 public abstract class Charset implements Comparable<Charset> {
@@ -125,12 +122,13 @@
     }
 
     /**
-     * Constructs a <code>Charset</code> object. Duplicated aliases are ignored.
+     * Constructs a <code>Charset</code> object. Duplicated aliases are
+     * ignored.
      * 
      * @param canonicalName
-     *            the canonical name of the charset
+     *            the canonical name of the charset.
      * @param aliases
-     *            an array containing all aliases of the charset
+     *            an array containing all aliases of the charset. May be null.
      * @throws IllegalCharsetNameException
      *             on an illegal value being supplied for either
      *             <code>canonicalName</code> or for any element of
@@ -162,16 +160,16 @@
     }
 
     /*
-     * Checks whether a character is a letter (ascii) which are defined in Java
-     * Spec.
+     * Checks whether a character is a letter (ascii) which are defined in the
+     * spec.
      */
     private static boolean isLetter(char c) {
         return ('a' <= c && c <= 'z') || ('A' <= c && c <= 'Z');
     }
 
     /*
-     * Checks whether a character is a digit (ascii) which are defined in Java
-     * Spec.
+     * Checks whether a character is a digit (ascii) which are defined in the
+     * spec.
      */
     private static boolean isDigit(char c) {
         return ('0' <= c && c <= '9');
@@ -317,8 +315,7 @@
      * The returned map contains mappings from canonical names to corresponding
      * instances of <code>Charset</code>. The canonical names can be considered
      * as case-insensitive.
-     * </p>
-     * 
+     *
      * @return an unmodifiable map of all available charsets supported by the
      *         runtime
      */
@@ -515,12 +512,12 @@
      * Gets a <code>Charset</code> instance for the specified charset name.
      * 
      * @param charsetName
-     *            the name of the charset
-     * @return a <code>Charset</code> instance for the specified charset name
+     *            the canonical name of the charset or an alias.
+     * @return a <code>Charset</code> instance for the specified charset name.
      * @throws IllegalCharsetNameException
-     *             If the specified charset name is illegal.
+     *             if the specified charset name is illegal.
      * @throws UnsupportedCharsetException
-     *             If the desired charset is not supported by this runtime.
+     *             if the desired charset is not supported by this runtime.
      */
     public static Charset forName(String charsetName) {
         Charset c = forNameInternal(charsetName);
@@ -534,10 +531,10 @@
      * Determines whether the specified charset is supported by this runtime.
      * 
      * @param charsetName
-     *            the name of the charset
-     * @return true if the specified charset is supported, otherwise false
+     *            the name of the charset.
+     * @return true if the specified charset is supported, otherwise false.
      * @throws IllegalCharsetNameException
-     *             If the specified charset name is illegal.
+     *             if the specified charset name is illegal.
      */
     public static boolean isSupported(String charsetName) {
         if (inForNameInternal  == true) {
@@ -572,23 +569,24 @@
      * Determines whether this charset is a super set of the given charset.
      * 
      * @param charset
-     *            a given charset
+     *            a given charset.
      * @return true if this charset is a super set of the given charset,
-     *         otherwise false
+     *         false if it's unknown or this charset is not a superset of
+     *         the given charset.
      */
     public abstract boolean contains(Charset charset);
 
     /**
-     * Gets a new instance of encoder for this charset.
+     * Gets a new instance of an encoder for this charset.
      * 
-     * @return a new instance of encoder for this charset
+     * @return a new instance of an encoder for this charset.
      */
     public abstract CharsetEncoder newEncoder();
 
     /**
-     * Gets a new instance of decoder for this charset.
+     * Gets a new instance of a decoder for this charset.
      * 
-     * @return a new instance of decoder for this charset
+     * @return a new instance of a decoder for this charset.
      */
     public abstract CharsetDecoder newDecoder();
 
@@ -604,7 +602,7 @@
     /**
      * Gets the set of this charset's aliases.
      * 
-     * @return an unmodifiable set of this charset's aliases
+     * @return an unmodifiable set of this charset's aliases.
      */
     public final Set<String> aliases() {
         return Collections.unmodifiableSet(this.aliasesSet);
@@ -613,7 +611,10 @@
     /**
      * Gets the name of this charset for the default locale.
      * 
-     * @return the name of this charset for the default locale
+     * <p>The default implementation returns the canonical name of this charset.
+     * Subclasses may return a localized display name.
+     *
+     * @return the name of this charset for the default locale.
      */
     public String displayName() {
         return this.canonicalName;
@@ -621,7 +622,10 @@
 
     /**
      * Gets the name of this charset for the specified locale.
-     * 
+     *
+     * <p>The default implementation returns the canonical name of this charset.
+     * Subclasses may return a localized display name.
+     *
      * @param l
      *            a certain locale
      * @return the name of this charset for the specified locale
@@ -631,7 +635,7 @@
     }
 
     /**
-     * Answers whether this charset is known to be registered in the IANA
+     * Indicates whether this charset is known to be registered in the IANA
      * Charset Registry.
      * 
      * @return true if the charset is known to be registered, otherwise returns
@@ -643,9 +647,9 @@
     }
 
     /**
-     * Answers true if this charset supports encoding, otherwise false.
+     * Returns true if this charset supports encoding, false otherwise.
      * 
-     * @return true
+     * @return true if this charset supports encoding, false otherwise.
      */
     public boolean canEncode() {
         return true;
@@ -657,11 +661,10 @@
      * <p>
      * The default action in case of encoding errors is
      * <code>CodingErrorAction.REPLACE</code>.
-     * </p>
-     * 
+     *
      * @param buffer
-     *            the character buffer containing the content to be encoded
-     * @return the result of the encoding
+     *            the character buffer containing the content to be encoded.
+     * @return the result of the encoding.
      */
     public final ByteBuffer encode(CharBuffer buffer) {
         try {
@@ -680,27 +683,25 @@
      * <p>
      * The default action in case of encoding errors is
      * <code>CodingErrorAction.REPLACE</code>.
-     * </p>
-     * 
+     *
      * @param s
-     *            the string to be encoded
-     * @return the result of the encoding
+     *            the string to be encoded.
+     * @return the result of the encoding.
      */
     public final ByteBuffer encode(String s) {
         return encode(CharBuffer.wrap(s));
     }
 
     /**
-     * Decodes the content of the give byte buffer and outputs to a character
-     * buffer that is to be returned.
+     * Decodes the content of the specified byte buffer and writes it to a
+     * character buffer that is to be returned.
      * <p>
      * The default action in case of decoding errors is
      * <code>CodingErrorAction.REPLACE</code>.
-     * </p>
      * 
      * @param buffer
-     *            the byte buffer containing the content to be decoded
-     * @return a character buffer containing the output of the decoding
+     *            the byte buffer containing the content to be decoded.
+     * @return a character buffer containing the output of the decoding.
      */
     public final CharBuffer decode(ByteBuffer buffer) {
 
@@ -722,12 +723,13 @@
      */
 
     /**
-     * Compares this charset with the given charset.
+     * Compares this charset with the given charset. This comparation is
+     * based on the case insensitive canonical names of the charsets.
      * 
      * @param charset
-     *            the given object to be compared with
+     *            the given object to be compared with.
      * @return a negative integer if less than the given object, a positive
-     *         integer if larger than it, or 0 if equal to it
+     *         integer if larger than it, or 0 if equal to it.
      */
     public final int compareTo(Charset charset) {
         return this.canonicalName.compareToIgnoreCase(charset.canonicalName);
@@ -744,8 +746,8 @@
      * considered to be equal if they have the same canonical name.
      * 
      * @param obj
-     *            the given object to be compared with
-     * @return true if they have the same canonical name, otherwise false
+     *            the given object to be compared with.
+     * @return true if they have the same canonical name, otherwise false.
      */
     @Override
     public final boolean equals(Object obj) {
@@ -759,7 +761,7 @@
     /**
      * Gets the hash code of this charset.
      * 
-     * @return the hash code of this charset
+     * @return the hash code of this charset.
      */
     @Override
     public final int hashCode() {
@@ -770,7 +772,7 @@
      * Gets a string representation of this charset. Usually this contains the
      * canonical name of the charset.
      * 
-     * @return a string representation of this charset
+     * @return a string representation of this charset.
      */
     @Override
     public final String toString() {
@@ -778,9 +780,9 @@
     }
 
     /**
-     * Gets the system default charset from jvm.
+     * Gets the system default charset from the virtual machine.
      * 
-     * @return the default charset
+     * @return the default charset.
      */
     public static Charset defaultCharset() {
         Charset defaultCharset = null;

Modified: harmony/enhanced/classlib/trunk/modules/nio_char/src/main/java/java/nio/charset/CharsetDecoder.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio_char/src/main/java/java/nio/charset/CharsetDecoder.java?rev=769094&r1=769093&r2=769094&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio_char/src/main/java/java/nio/charset/CharsetDecoder.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio_char/src/main/java/java/nio/charset/CharsetDecoder.java Mon Apr 27 18:39:23 2009
@@ -24,68 +24,62 @@
 import org.apache.harmony.niochar.internal.nls.Messages;
 
 /**
- * An converter that can convert bytes sequence in some charset to 16-bit
+ * A converter that can convert a byte sequence from a charset into a 16-bit
  * Unicode character sequence.
  * <p>
- * The input byte sequence is wrapped by {@link java.nio.ByteBuffer ByteBuffer}
- * and the output character sequence is {@link java.nio.CharBuffer CharBuffer}.
- * A decoder instance should be used in following sequence, which is referred to
- * as a decoding operation:
+ * The input byte sequence is wrapped by a
+ * {@link java.nio.ByteBuffer ByteBuffer} and the output character sequence is a
+ * {@link java.nio.CharBuffer CharBuffer}. A decoder instance should be used in
+ * the following sequence, which is referred to as a decoding operation:
  * <ol>
- * <li>Invoking the {@link #reset() reset} method to reset the decoder if the
+ * <li>invoking the {@link #reset() reset} method to reset the decoder if the
  * decoder has been used;</li>
- * <li>Invoking the {@link #decode(ByteBuffer, CharBuffer, boolean) decode}
+ * <li>invoking the {@link #decode(ByteBuffer, CharBuffer, boolean) decode}
  * method until the additional input is not needed, the <code>endOfInput</code>
  * parameter must be set to false, the input buffer must be filled and the
  * output buffer must be flushed between invocations;</li>
- * <li>Invoking the {@link #decode(ByteBuffer, CharBuffer, boolean) decode}
- * method last time, and the the <code>endOfInput</code> parameter must be set
- * to true</li>
- * <li>Invoking the {@link #flush(CharBuffer) flush} method to flush the
+ * <li>invoking the {@link #decode(ByteBuffer, CharBuffer, boolean) decode}
+ * method for the last time, and then the <code>endOfInput</code> parameter
+ * must be set to true;</li>
+ * <li>invoking the {@link #flush(CharBuffer) flush} method to flush the
  * output.</li>
  * </ol>
- * </p>
  * <p>
  * The {@link #decode(ByteBuffer, CharBuffer, boolean) decode} method will
- * convert as many bytes as possible, and the process won't stop except the
- * input bytes has been run out of, the output buffer has been filled or some
- * error has happened. A {@link CoderResult CoderResult} instance will be
- * returned to indicate the stop reason, and the invoker can identify the result
- * and choose further action, which can include filling the input buffer,
- * flushing the output buffer, recovering from error and trying again.
- * </p>
+ * convert as many bytes as possible, and the process won't stop until the input
+ * bytes have run out, the output buffer has been filled or some error has
+ * happened. A {@link CoderResult CoderResult} instance will be returned to
+ * indicate the stop reason, and the invoker can identify the result and choose
+ * further action, which includes filling the input buffer, flushing the output
+ * buffer or recovering from an error and trying again.
  * <p>
- * There are two common decoding errors. One is named as malformed and it is
- * returned when the input byte sequence is illegal for current specific
- * charset, the other is named as unmappable character and it is returned when a
+ * There are two common decoding errors. One is named malformed and it is
+ * returned when the input byte sequence is illegal for the current specific
+ * charset, the other is named unmappable character and it is returned when a
  * problem occurs mapping a legal input byte sequence to its Unicode character
  * equivalent.
- * </p>
  * <p>
- * The two errors can be handled in three ways, the default one is to report the
+ * Both errors can be handled in three ways, the default one is to report the
  * error to the invoker by a {@link CoderResult CoderResult} instance, and the
  * alternatives are to ignore it or to replace the erroneous input with the
- * replacement string. The replacement string is "&#92;uFFFD" by default and can be
+ * replacement string. The replacement string is "\uFFFD" by default and can be
  * changed by invoking {@link #replaceWith(String) replaceWith} method. The
  * invoker of this decoder can choose one way by specifying a
  * {@link CodingErrorAction CodingErrorAction} instance for each error type via
  * {@link #onMalformedInput(CodingErrorAction) onMalformedInput} method and
  * {@link #onUnmappableCharacter(CodingErrorAction) onUnmappableCharacter}
  * method.
- * </p>
  * <p>
- * This class is abstract class and encapsulate many common operations of
- * decoding process for all charsets. Decoder for specific charset should extend
- * this class and need only implement
- * {@link #decodeLoop(ByteBuffer, CharBuffer) decodeLoop} method for basic
- * decoding loop. If a subclass maintains internal state, it should override the
- * {@link #implFlush(CharBuffer) implFlush} method and
+ * This is an abstract class and encapsulates many common operations of the
+ * decoding process for all charsets. Decoders for a specific charset should
+ * extend this class and need only to implement the
+ * {@link #decodeLoop(ByteBuffer, CharBuffer) decodeLoop} method for the basic
+ * decoding. If a subclass maintains an internal state, it should override the
+ * {@link #implFlush(CharBuffer) implFlush} method and the
  * {@link #implReset() implReset} method in addition.
- * </p>
  * <p>
  * This class is not thread-safe.
- * </p>
- * 
+ *
  * @see java.nio.charset.Charset
  * @see java.nio.charset.CharsetEncoder
  */
@@ -124,23 +118,22 @@
     private int status;
 
     /**
-     * Construct a new <code>CharsetDecoder</code> using given
+     * Constructs a new <code>CharsetDecoder</code> using the given
      * <code>Charset</code>, average number and maximum number of characters
      * created by this decoder for one input byte, and the default replacement
-     * string "&#92;uFFFD".
+     * string "\uFFFD".
      * 
      * @param charset
-     *            this decoder's <code>Charset</code>, which create this
-     *            decoder
+     *            the <code>Charset</code> to be used by this decoder.
      * @param averageCharsPerByte
-     *            average number of characters created by this decoder for one
-     *            input byte, must be positive
+     *            the average number of characters created by this decoder for
+     *            one input byte, must be positive.
      * @param maxCharsPerByte
-     *            maximum number of characters created by this decoder for one
-     *            input byte, must be positive
+     *            the maximum number of characters created by this decoder for
+     *            one input byte, must be positive.
      * @throws IllegalArgumentException
      *             if <code>averageCharsPerByte</code> or
-     *             <code>maxCharsPerByte</code> is negative
+     *             <code>maxCharsPerByte</code> is negative.
      */
     protected CharsetDecoder(Charset charset, float averageCharsPerByte,
             float maxCharsPerByte) {
@@ -162,57 +155,57 @@
     }
 
     /**
-     * get the average number of characters created by this decoder for single
-     * input byte
+     * Gets the average number of characters created by this decoder for a
+     * single input byte.
      * 
-     * @return the average number of characters created by this decoder for
-     *         single input byte
+     * @return the average number of characters created by this decoder for a
+     *         single input byte.
      */
     public final float averageCharsPerByte() {
         return averChars;
     }
 
     /**
-     * Get the <code>Charset</code> which creates this decoder.
+     * Gets the <code>Charset</code> which this decoder uses.
      * 
-     * @return the <code>Charset</code> which creates this decoder
+     * @return the <code>Charset</code> which this decoder uses.
      */
     public final Charset charset() {
         return cs;
     }
 
     /**
-     * This is a facade method for decoding operation.
+     * This is a facade method for the decoding operation.
      * <p>
      * This method decodes the remaining byte sequence of the given byte buffer
      * into a new character buffer. This method performs a complete decoding
      * operation, resets at first, then decodes, and flushes at last.
-     * </p>
      * <p>
-     * This method should not be invoked if another decode operation is ongoing.
-     * </p>
-     * 
+     * This method should not be invoked while another {@code decode} operation
+     * is ongoing.
+     *
      * @param in
-     *            the input buffer
+     *            the input buffer.
      * @return a new <code>CharBuffer</code> containing the the characters
      *         produced by this decoding operation. The buffer's limit will be
-     *         the position of last character in buffer, and the position will
-     *         be zero
+     *         the position of the last character in the buffer, and the
+     *         position will be zero.
      * @throws IllegalStateException
-     *             if another decoding operation is ongoing
+     *             if another decoding operation is ongoing.
      * @throws MalformedInputException
-     *             if illegal input byte sequence for this charset encountered,
-     *             and the action for malformed error is
+     *             if an illegal input byte sequence for this charset was
+     *             encountered, and the action for malformed error is
      *             {@link CodingErrorAction#REPORT CodingErrorAction.REPORT}
      * @throws UnmappableCharacterException
-     *             if legal but unmappable input byte sequence for this charset
-     *             encountered, and the action for unmappable character error is
+     *             if a legal but unmappable input byte sequence for this
+     *             charset was encountered, and the action for unmappable
+     *             character error is
      *             {@link CodingErrorAction#REPORT CodingErrorAction.REPORT}.
      *             Unmappable means the byte sequence at the input buffer's
      *             current position cannot be mapped to a Unicode character
      *             sequence.
      * @throws CharacterCodingException
-     *             if other exception happened during the decode operation
+     *             if another exception happened during the decode operation.
      */
     public final CharBuffer decode(ByteBuffer in)
             throws CharacterCodingException {
@@ -282,7 +275,6 @@
      * <p>
      * The buffers' position will be changed with the reading and writing
      * operation, but their limits and marks will be kept intact.
-     * </p>
      * <p>
      * A <code>CoderResult</code> instance will be returned according to
      * following rules:
@@ -298,49 +290,47 @@
      * operation may be regarded as complete. Otherwise, this method should be
      * called once more with additional input.</li>
      * <li>A {@link CoderResult#malformedForLength(int) malformed input} result
-     * indicates that some malformed input error encountered, and the erroneous
-     * bytes start at the input buffer's position and their number can be got by
-     * result's {@link CoderResult#length() length}. This kind of result can be
-     * returned only if the malformed action is
+     * indicates that some malformed input error has been encountered, and the
+     * erroneous bytes start at the input buffer's position and their number can
+     * be got by result's {@link CoderResult#length() length}. This kind of
+     * result can be returned only if the malformed action is
      * {@link CodingErrorAction#REPORT CodingErrorAction.REPORT}. </li>
      * <li>A {@link CoderResult#unmappableForLength(int) unmappable character}
-     * result indicates that some unmappable character error encountered, and
-     * the erroneous bytes start at the input buffer's position and their number
-     * can be got by result's {@link CoderResult#length() length}. This kind of
-     * result can be returned only if the unmappable character action is
+     * result indicates that some unmappable character error has been
+     * encountered, and the erroneous bytes start at the input buffer's position
+     * and their number can be got by result's
+     * {@link CoderResult#length() length}. This kind of result can be returned
+     * only if the unmappable character action is
      * {@link CodingErrorAction#REPORT CodingErrorAction.REPORT}. </li>
      * </ul>
-     * </p>
      * <p>
-     * The <code>endOfInput</code> parameter indicates that if the invoker can
-     * provider further input. This parameter is true if and only if the bytes
-     * in current input buffer are all inputs for this decoding operation. Note
-     * that it is common and won't cause error that the invoker sets false and
-     * then finds no more input available; while it may cause error that the
-     * invoker always sets true in several consecutive invocations so that any
-     * remaining input will be treated as malformed input.
-     * </p>
+     * The <code>endOfInput</code> parameter indicates that the invoker cannot
+     * provide further input. This parameter is true if and only if the bytes in
+     * current input buffer are all inputs for this decoding operation. Note
+     * that it is common and won't cause an error if the invoker sets false and
+     * then can't provide more input, while it may cause an error if the invoker
+     * always sets true in several consecutive invocations. This would make the
+     * remaining input to be treated as malformed input.
      * <p>
-     * This method invokes
+     * This method invokes the
      * {@link #decodeLoop(ByteBuffer, CharBuffer) decodeLoop} method to
-     * implement basic decode logic for specific charset.
-     * </p>
-     * 
+     * implement the basic decode logic for a specific charset.
+     *
      * @param in
-     *            the input buffer
+     *            the input buffer.
      * @param out
-     *            the output buffer
+     *            the output buffer.
      * @param endOfInput
-     *            true if all the input characters have been provided
+     *            true if all the input characters have been provided.
      * @return a <code>CoderResult</code> instance which indicates the reason
-     *         of termination
+     *         of termination.
      * @throws IllegalStateException
      *             if decoding has started or no more input is needed in this
      *             decoding progress.
      * @throws CoderMalfunctionError
      *             if the {@link #decodeLoop(ByteBuffer, CharBuffer) decodeLoop}
      *             method threw an <code>BufferUnderflowException</code> or
-     *             <code>BufferOverflowException</code>
+     *             <code>BufferOverflowException</code>.
      */
     public final CoderResult decode(ByteBuffer in, CharBuffer out,
             boolean endOfInput) {
@@ -401,96 +391,96 @@
     }
 
     /**
-     * Decode bytes into characters. This method is called by
+     * Decodes bytes into characters. This method is called by the
      * {@link #decode(ByteBuffer, CharBuffer, boolean) decode} method.
-     * 
+     * <p>
      * This method will implement the essential decoding operation, and it won't
      * stop decoding until either all the input bytes are read, the output
-     * buffer is filled, or some exception encountered. And then it will return
-     * a <code>CoderResult</code> object indicating the result of current
+     * buffer is filled, or some exception is encountered. Then it will return a
+     * <code>CoderResult</code> object indicating the result of current
      * decoding operation. The rules to construct the <code>CoderResult</code>
-     * is same as the {@link #decode(ByteBuffer, CharBuffer, boolean) decode}.
-     * When exception encountered in the decoding operation, most implementation
-     * of this method will return a relevant result object to
+     * are the same as for
+     * {@link #decode(ByteBuffer, CharBuffer, boolean) decode}. When an
+     * exception is encountered in the decoding operation, most implementations
+     * of this method will return a relevant result object to the
      * {@link #decode(ByteBuffer, CharBuffer, boolean) decode} method, and some
      * performance optimized implementation may handle the exception and
      * implement the error action itself.
-     * 
+     * <p>
      * The buffers are scanned from their current positions, and their positions
      * will be modified accordingly, while their marks and limits will be
      * intact. At most {@link ByteBuffer#remaining() in.remaining()} characters
      * will be read, and {@link CharBuffer#remaining() out.remaining()} bytes
      * will be written.
-     * 
-     * Note that some implementation may pre-scan the input buffer and return
+     * <p>
+     * Note that some implementations may pre-scan the input buffer and return a
      * <code>CoderResult.UNDERFLOW</code> until it receives sufficient input.
      * 
      * @param in
-     *            the input buffer
+     *            the input buffer.
      * @param out
-     *            the output buffer
-     * @return a <code>CoderResult</code> instance indicating the result
+     *            the output buffer.
+     * @return a <code>CoderResult</code> instance indicating the result.
      */
     protected abstract CoderResult decodeLoop(ByteBuffer in, CharBuffer out);
 
     /**
-     * Get the charset detected by this decoder, this method is optional.
+     * Gets the charset detected by this decoder; this method is optional.
      * <p>
      * If implementing an auto-detecting charset, then this decoder returns the
      * detected charset from this method when it is available. The returned
      * charset will be the same for the rest of the decode operation.
-     * </p>
      * <p>
-     * If insufficient bytes have been read to determine the charset,
+     * If insufficient bytes have been read to determine the charset, an
      * <code>IllegalStateException</code> will be thrown.
-     * </p>
      * <p>
      * The default implementation always throws
      * <code>UnsupportedOperationException</code>, so it should be overridden
-     * by subclass if needed.
-     * </p>
-     * 
+     * by a subclass if needed.
+     *
      * @return the charset detected by this decoder, or null if it is not yet
-     *         determined
+     *         determined.
      * @throws UnsupportedOperationException
-     *             if this decoder does not implement an auto-detecting charset
+     *             if this decoder does not implement an auto-detecting charset.
      * @throws IllegalStateException
-     *             if insufficient bytes have been read to determine the charset
+     *             if insufficient bytes have been read to determine the
+     *             charset.
      */
     public Charset detectedCharset() {
         throw new UnsupportedOperationException();
     }
 
     /**
-     * Flush this decoder.
+     * Flushes this decoder.
      * 
      * This method will call {@link #implFlush(CharBuffer) implFlush}. Some
      * decoders may need to write some characters to the output buffer when they
-     * have read all input bytes, subclasses can overridden
-     * {@link #implFlush(CharBuffer) implFlush} to perform writing action.
-     * 
-     * The maximum number of written bytes won't larger than
-     * {@link CharBuffer#remaining() out.remaining()}. If some decoder want to
-     * write more bytes than output buffer's remaining spaces, then
+     * have read all input bytes; subclasses can override
+     * {@link #implFlush(CharBuffer) implFlush} to perform the writing operation.
+     * <p>
+     * The maximum number of written bytes won't be larger than
+     * {@link CharBuffer#remaining() out.remaining()}. If some decoder wants to
+     * write more bytes than an output buffer's remaining space allows, then a
      * <code>CoderResult.OVERFLOW</code> will be returned, and this method
-     * must be called again with a character buffer that has more spaces.
-     * Otherwise this method will return <code>CoderResult.UNDERFLOW</code>,
-     * which means one decoding process has been completed successfully.
-     * 
+     * must be called again with a character buffer that has more remaining
+     * space. Otherwise this method will return
+     * <code>CoderResult.UNDERFLOW</code>, which means one decoding process
+     * has been completed successfully.
+     * <p>
      * During the flush, the output buffer's position will be changed
      * accordingly, while its mark and limit will be intact.
-     * 
+     *
      * @param out
-     *            the given output buffer
+     *            the given output buffer.
      * @return <code>CoderResult.UNDERFLOW</code> or
-     *         <code>CoderResult.OVERFLOW</code>
+     *         <code>CoderResult.OVERFLOW</code>.
      * @throws IllegalStateException
      *             if this decoder hasn't read all input bytes during one
      *             decoding process, which means neither after calling
      *             {@link #decode(ByteBuffer) decode(ByteBuffer)} nor after
      *             calling {@link #decode(ByteBuffer, CharBuffer, boolean)
-     *             decode(ByteBuffer, CharBuffer, boolean)} with true value for
-     *             the last boolean parameter
+     *             decode(ByteBuffer, CharBuffer, boolean)} with true as value
+     *             for the last boolean parameter.
      */
     public final CoderResult flush(CharBuffer out) {
         if (status != END && status != INIT) {
@@ -504,96 +494,95 @@
     }
 
     /**
-     * Flush this decoder. Default implementation does nothing and always return
-     * <code>CoderResult.UNDERFLOW</code>, and this method can be overridden
-     * if needed.
+     * Flushes this decoder. The default implementation does nothing and always
+     * returns <code>CoderResult.UNDERFLOW</code>; this method can be
+     * overridden if needed.
      * 
      * @param out
-     *            the output buffer
+     *            the output buffer.
      * @return <code>CoderResult.UNDERFLOW</code> or
-     *         <code>CoderResult.OVERFLOW</code>
+     *         <code>CoderResult.OVERFLOW</code>.
      */
     protected CoderResult implFlush(CharBuffer out) {
         return CoderResult.UNDERFLOW;
     }
 
     /**
-     * Notify that this decoder's <code>CodingErrorAction</code> specified for
-     * malformed input error has been changed. Default implementation does
-     * nothing, and this method can be overridden if needed.
+     * Notifies that this decoder's <code>CodingErrorAction</code> specified
+     * for malformed input error has been changed. The default implementation
+     * does nothing; this method can be overridden if needed.
      * 
      * @param newAction
-     *            The new action
+     *            the new action.
      */
     protected void implOnMalformedInput(CodingErrorAction newAction) {
         // default implementation is empty
     }
 
     /**
-     * Notify that this decoder's <code>CodingErrorAction</code> specified for
-     * unmappable character error has been changed. Default implementation does
-     * nothing, and this method can be overridden if needed.
+     * Notifies that this decoder's <code>CodingErrorAction</code> specified
+     * for unmappable character error has been changed. The default
+     * implementation does nothing; this method can be overridden if needed.
      * 
      * @param newAction
-     *            The new action
+     *            the new action.
      */
     protected void implOnUnmappableCharacter(CodingErrorAction newAction) {
         // default implementation is empty
     }
 
     /**
-     * Notify that this decoder's replacement has been changed. Default
-     * implementation does nothing, and this method can be overridden if needed.
+     * Notifies that this decoder's replacement has been changed. The default
+     * implementation does nothing; this method can be overridden if needed.
      * 
      * @param newReplacement
-     *            the new replacement string
+     *            the new replacement string.
      */
     protected void implReplaceWith(String newReplacement) {
         // default implementation is empty
     }
 
     /**
-     * Reset this decoder's charset related state. Default implementation does
-     * nothing, and this method can be overridden if needed.
+     * Reset this decoder's charset related state. The default implementation
+     * does nothing; this method can be overridden if needed.
      */
     protected void implReset() {
         // default implementation is empty
     }
 
     /**
-     * Get if this decoder implements an auto-detecting charset.
+     * Indicates whether this decoder implements an auto-detecting charset.
      * 
      * @return <code>true</code> if this decoder implements an auto-detecting
-     *         charset
+     *         charset.
      */
     public boolean isAutoDetecting() {
         return false;
     }
 
     /**
-     * Get if this decoder has detected a charset, this method is optional.
+     * Indicates whether this decoder has detected a charset; this method is
+     * optional.
      * <p>
      * If this decoder implements an auto-detecting charset, then this method
      * may start to return true during decoding operation to indicate that a
      * charset has been detected in the input bytes and that the charset can be
-     * retrieved by invoking {@link #detectedCharset() detectedCharset} method.
-     * </p>
+     * retrieved by invoking the {@link #detectedCharset() detectedCharset}
+     * method.
      * <p>
      * Note that a decoder that implements an auto-detecting charset may still
      * succeed in decoding a portion of the given input even when it is unable
      * to detect the charset. For this reason users should be aware that a
      * <code>false</code> return value does not indicate that no decoding took
      * place.
-     * </p>
      * <p>
      * The default implementation always throws an
      * <code>UnsupportedOperationException</code>; it should be overridden by
-     * subclass if needed.
-     * </p>
+     * a subclass if needed.
      * 
-     * @return <code>true</code> this decoder has detected a charset
+     * @return <code>true</code> if this decoder has detected a charset.
      * @throws UnsupportedOperationException
-     *             if this decoder doesn't implement an auto-detecting charset
+     *             if this decoder doesn't implement an auto-detecting charset.
      */
     public boolean isCharsetDetected() {
         throw new UnsupportedOperationException();
@@ -601,38 +590,38 @@
 
     /**
      * Gets this decoder's <code>CodingErrorAction</code> when malformed input
-     * occurred during decoding process.
+     * occurred during the decoding process.
      * 
      * @return this decoder's <code>CodingErrorAction</code> when malformed
-     *         input occurred during decoding process.
+     *         input occurred during the decoding process.
      */
     public CodingErrorAction malformedInputAction() {
         return malformAction;
     }
 
     /**
-     * Get the maximum number of characters which can be created by this decoder
-     * for one input byte, must be positive
+     * Gets the maximum number of characters which can be created by this
+     * decoder for one input byte, must be positive.
      * 
      * @return the maximum number of characters which can be created by this
-     *         decoder for one input byte, must be positive
+     *         decoder for one input byte, must be positive.
      */
     public final float maxCharsPerByte() {
         return maxChars;
     }
 
     /**
-     * Set this decoder's action on malformed input error.
+     * Sets this decoder's action on malformed input errors.
      * 
      * This method will call the
      * {@link #implOnMalformedInput(CodingErrorAction) implOnMalformedInput}
      * method with the given new action as argument.
      * 
      * @param newAction
-     *            the new action on malformed input error
-     * @return this decoder
+     *            the new action on malformed input error.
+     * @return this decoder.
      * @throws IllegalArgumentException
-     *             if the given newAction is null
+     *             if {@code newAction} is {@code null}.
      */
     public final CharsetDecoder onMalformedInput(CodingErrorAction newAction) {
         if (null == newAction) {
@@ -644,17 +633,17 @@
     }
 
     /**
-     * Set this decoder's action on unmappable character error.
+     * Sets this decoder's action on unmappable character errors.
      * 
      * This method will call the
      * {@link #implOnUnmappableCharacter(CodingErrorAction) implOnUnmappableCharacter}
      * method with the given new action as argument.
      * 
      * @param newAction
-     *            the new action on unmappable character error
-     * @return this decoder
+     *            the new action on unmappable character error.
+     * @return this decoder.
      * @throws IllegalArgumentException
-     *             if the given newAction is null
+     *             if {@code newAction} is {@code null}.
      */
     public final CharsetDecoder onUnmappableCharacter(
             CodingErrorAction newAction) {
@@ -667,28 +656,29 @@
     }
 
     /**
-     * Get the replacement string, which is never null or empty
+     * Gets the replacement string, which is never null or empty.
      * 
-     * @return the replacement string, cannot be null or empty
+     * @return the replacement string, cannot be null or empty.
      */
     public final String replacement() {
         return replace;
     }
 
     /**
-     * Set new replacement value.
+     * Sets the new replacement string.
      * 
      * This method first checks the given replacement's validity, then changes
-     * the replacement value, and at last calls
+     * the replacement value, and at last calls the
      * {@link #implReplaceWith(String) implReplaceWith} method with the given
      * new replacement as argument.
      * 
      * @param newReplacement
-     *            the replacement string, cannot be null or empty
-     * @return this decoder
+     *            the replacement string, cannot be null or empty. Its length
+     *            cannot be larger than {@link #maxCharsPerByte()}.
+     * @return this decoder.
      * @throws IllegalArgumentException
      *             if the given replacement cannot satisfy the requirement
-     *             mentioned above
+     *             mentioned above.
      */
     public final CharsetDecoder replaceWith(String newReplacement) {
         if (null == newReplacement || newReplacement.length() == 0) {
@@ -706,11 +696,11 @@
     }
 
     /**
-     * Reset this decoder. This method will reset internal status, and then call
-     * <code>implReset()</code> to reset any status related to specific
-     * charset.
+     * Resets this decoder. This method will reset the internal status, and then
+     * calls <code>implReset()</code> to reset any status related to the
+     * specific charset.
      * 
-     * @return this decoder
+     * @return this decoder.
      */
     public final CharsetDecoder reset() {
         status = INIT;
@@ -719,11 +709,11 @@
     }
 
     /**
-     * Gets this decoder's <code>CodingErrorAction</code> when unmappable
-     * character occurred during decoding process.
+     * Gets this decoder's <code>CodingErrorAction</code> when an unmappable
+     * character error occurred during the decoding process.
      * 
-     * @return this decoder's <code>CodingErrorAction</code> when unmappable
-     *         character occurred during decoding process.
+     * @return this decoder's <code>CodingErrorAction</code> when an
+     *         unmappable character error occurred during the decoding process.
      */
     public CodingErrorAction unmappableCharacterAction() {
         return unmapAction;

Modified: harmony/enhanced/classlib/trunk/modules/nio_char/src/main/java/java/nio/charset/CharsetEncoder.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio_char/src/main/java/java/nio/charset/CharsetEncoder.java?rev=769094&r1=769093&r2=769094&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio_char/src/main/java/java/nio/charset/CharsetEncoder.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio_char/src/main/java/java/nio/charset/CharsetEncoder.java Mon Apr 27 18:39:23 2009
@@ -24,67 +24,62 @@
 import org.apache.harmony.niochar.internal.nls.Messages;
 
 /**
- * An converter that can convert 16-bit Unicode character sequence to byte
- * sequence in some charset .
+ * A converter that can converts a 16-bit Unicode character sequence to a byte
+ * sequence in some charset.
  * <p>
- * The input character sequence is wrapped by
- * {@link java.nio.CharBuffer CharBuffer} and the output character sequence is
- * {@link java.nio.ByteBuffer ByteBuffer}. A encoder instance should be used in
- * following sequence, which is referred to as a encoding operation:
+ * The input character sequence is wrapped by a
+ * {@link java.nio.CharBuffer CharBuffer} and the output character sequence is a
+ * {@link java.nio.ByteBuffer ByteBuffer}. An encoder instance should be used
+ * in the following sequence, which is referred to as a encoding operation:
  * <ol>
- * <li>Invoking the {@link #reset() reset} method to reset the encoder if the
+ * <li>invoking the {@link #reset() reset} method to reset the encoder if the
  * encoder has been used;</li>
- * <li>Invoking the {@link #encode(CharBuffer, ByteBuffer, boolean) encode}
+ * <li>invoking the {@link #encode(CharBuffer, ByteBuffer, boolean) encode}
  * method until the additional input is not needed, the <code>endOfInput</code>
  * parameter must be set to false, the input buffer must be filled and the
  * output buffer must be flushed between invocations;</li>
- * <li>Invoking the {@link #encode(CharBuffer, ByteBuffer, boolean) encode}
- * method last time, and the the <code>endOfInput</code> parameter must be set
- * to true</li>
- * <li>Invoking the {@link #flush(ByteBuffer) flush} method to flush the
+ * <li>invoking the {@link #encode(CharBuffer, ByteBuffer, boolean) encode}
+ * method for the last time and the <code>endOfInput</code> parameter must be
+ * set to {@code true}</li>
+ * <li>invoking the {@link #flush(ByteBuffer) flush} method to flush the
  * output.</li>
  * </ol>
- * </p>
  * <p>
  * The {@link #encode(CharBuffer, ByteBuffer, boolean) encode} method will
- * convert as many characters as possible, and the process won't stop except the
- * input characters has been run out of, the output buffer has been filled or
- * some error has happened. A {@link CoderResult CoderResult} instance will be
+ * convert as many characters as possible, and the process won't stop until the
+ * input characters have run out, the output buffer has been filled or some
+ * error has happened. A {@link CoderResult CoderResult} instance will be
  * returned to indicate the stop reason, and the invoker can identify the result
- * and choose further action, which can include filling the input buffer,
- * flushing the output buffer, recovering from error and trying again.
- * </p>
+ * and choose further action, which includes filling the input buffer, flushing
+ * the output buffer or recovering from an error and trying again.
  * <p>
- * There are two common encoding errors. One is named as malformed and it is
- * returned when the input content is illegal 16-bit Unicode character sequence,
- * the other is named as unmappable character and occurs when there is a problem
- * mapping the input to a valid byte sequence in the specific charset.
- * </p>
+ * There are two common encoding errors. One is named malformed and it is
+ * returned when the input content is an illegal 16-bit Unicode character
+ * sequence, the other is named unmappable character and occurs when there is a
+ * problem mapping the input to a valid byte sequence in the specified charset.
  * <p>
- * The two errors can be handled in three ways, the default one is to report the
+ * Both errors can be handled in three ways, the default one is to report the
  * error to the invoker by a {@link CoderResult CoderResult} instance, and the
  * alternatives are to ignore it or to replace the erroneous input with the
- * replacement byte array. The replacement byte array is {(byte)'?'} by default
- * and can be changed by invoking {@link #replaceWith(byte[]) replaceWith}
- * method. The invoker of this encoder can choose one way by specifying a
+ * replacement byte array. The replacement byte array is '{@code ?}' by
+ * default and can be changed by invoking the
+ * {@link #replaceWith(byte[]) replaceWith} method. The invoker of this encoder
+ * can choose one way by specifying a
  * {@link CodingErrorAction CodingErrorAction} instance for each error type via
- * {@link #onMalformedInput(CodingErrorAction) onMalformedInput} method and
- * {@link #onUnmappableCharacter(CodingErrorAction) onUnmappableCharacter}
+ * the {@link #onMalformedInput(CodingErrorAction) onMalformedInput} method and
+ * the {@link #onUnmappableCharacter(CodingErrorAction) onUnmappableCharacter}
  * method.
- * </p>
  * <p>
- * This class is abstract class and encapsulate many common operations of
- * encoding process for all charsets. encoder for specific charset should extend
- * this class and need only implement
+ * This class is abstract and encapsulates many common operations of the
+ * encoding process for all charsets. Encoders for a specific charset should
+ * extend this class and need only to implement the
  * {@link #encodeLoop(CharBuffer, ByteBuffer) encodeLoop} method for basic
- * encoding loop. If a subclass maintains internal state, it should override the
- * {@link #implFlush(ByteBuffer) implFlush} method and
+ * encoding. If a subclass maintains an internal state, it should override the
+ * {@link #implFlush(ByteBuffer) implFlush} method and the
  * {@link #implReset() implReset} method in addition.
- * </p>
  * <p>
  * This class is not thread-safe.
- * </p>
- * 
+ *
  * @see java.nio.charset.Charset
  * @see java.nio.charset.CharsetDecoder
  */
@@ -127,22 +122,21 @@
     private CharsetDecoder decoder;
 
     /**
-     * Construct a new <code>CharsetEncoder</code> using given
+     * Constructs a new <code>CharsetEncoder</code> using the given
      * <code>Charset</code>, average number and maximum number of bytes
      * created by this encoder for one input character.
      * 
      * @param cs
-     *            this encoder's <code>Charset</code>, which create this
-     *            encoder
+     *            the <code>Charset</code> to be used by this encoder.
      * @param averageBytesPerChar
      *            average number of bytes created by this encoder for one input
-     *            character, must be positive
+     *            character, must be positive.
      * @param maxBytesPerChar
      *            maximum number of bytes which can be created by this encoder
-     *            for one input character, must be positive
+     *            for one input character, must be positive.
      * @throws IllegalArgumentException
      *             if <code>maxBytesPerChar</code> or
-     *             <code>averageBytePerChar</code> is negative
+     *             <code>averageBytesPerChar</code> is negative.
      */
     protected CharsetEncoder(Charset cs, float averageBytesPerChar,
             float maxBytesPerChar) {
@@ -151,26 +145,25 @@
     }
 
     /**
-     * Construct a new <code>CharsetEncoder</code> using given
-     * <code>Charset</code>, replace byte array, average number and maximum
-     * number of bytes created by this encoder for one input character.
+     * Constructs a new <code>CharsetEncoder</code> using the given
+     * <code>Charset</code>, replacement byte array, average number and
+     * maximum number of bytes created by this encoder for one input character.
      * 
      * @param cs
-     *            the this encoder's <code>Charset</code>, which create this
-     *            encoder
+     *            the <code>Charset</code> to be used by this encoder.
      * @param averageBytesPerChar
-     *            average number of bytes created by this encoder for single
-     *            input character, must be positive
+     *            average number of bytes created by this encoder for one single
+     *            input character, must be positive.
      * @param maxBytesPerChar
      *            maximum number of bytes which can be created by this encoder
-     *            for single input character, must be positive
+     *            for one single input character, must be positive.
      * @param replacement
      *            the replacement byte array, cannot be null or empty, its
-     *            length cannot larger than <code>maxBytesPerChar</code>, and
-     *            must be legal replacement, which can be justified by
-     *            {@link #isLegalReplacement(byte[]) isLegalReplacement}
+     *            length cannot be larger than <code>maxBytesPerChar</code>,
+     *            and must be a legal replacement, which can be justified by
+     *            {@link #isLegalReplacement(byte[]) isLegalReplacement}.
      * @throws IllegalArgumentException
-     *             if any parameters are invalid
+     *             if any parameters are invalid.
      */
     protected CharsetEncoder(Charset cs, float averageBytesPerChar,
             float maxBytesPerChar, byte[] replacement) {
@@ -192,31 +185,31 @@
     }
 
     /**
-     * get the average number of bytes created by this encoder for single input
-     * character
+     * Gets the average number of bytes created by this encoder for a single
+     * input character.
      * 
-     * @return the average number of bytes created by this encoder for single
-     *         input character
+     * @return the average number of bytes created by this encoder for a single
+     *         input character.
      */
     public final float averageBytesPerChar() {
         return averBytes;
     }
 
     /**
-     * Check if given character can be encoded by this encoder.
-     * 
+     * Checks if the given character can be encoded by this encoder.
+     * <p>
      * Note that this method can change the internal status of this encoder, so
-     * it should not be called when another encode process is ongoing, otherwise
-     * it will throw <code>IllegalStateException</code>.
-     * 
+     * it should not be called when another encoding process is ongoing,
+     * otherwise it will throw an <code>IllegalStateException</code>.
+     * <p>
      * This method can be overridden for performance improvement.
-     * 
+     *
      * @param c
-     *            the given encoder
-     * @return true if given character can be encoded by this encoder
+     *            the given encoder.
+     * @return true if given character can be encoded by this encoder.
      * @throws IllegalStateException
-     *             if another encode process is ongoing so that current internal
-     *             status is neither RESET or FLUSH
+     *             if another encode process is ongoing so that the current
+     *             internal status is neither RESET or FLUSH.
      */
     public boolean canEncode(char c) {
         return implCanEncode(CharBuffer.wrap(new char[] { c }));
@@ -248,21 +241,21 @@
     }
 
     /**
-     * Check if given <code>CharSequence</code> can be encoded by this
+     * Checks if a given <code>CharSequence</code> can be encoded by this
      * encoder.
      * 
      * Note that this method can change the internal status of this encoder, so
      * it should not be called when another encode process is ongoing, otherwise
-     * it will throw <code>IllegalStateException</code>.
+     * it will throw an <code>IllegalStateException</code>.
      * 
      * This method can be overridden for performance improvement.
      * 
      * @param sequence
-     *            the given <code>CharSequence</code>
-     * @return true if given <code>CharSequence</code> can be encoded by this
-     *         encoder
+     *            the given <code>CharSequence</code>.
+     * @return true if the given <code>CharSequence</code> can be encoded by
+     *         this encoder.
      * @throws IllegalStateException
-     *             if current internal status is neither RESET or FLUSH
+     *             if current internal status is neither RESET or FLUSH.
      */
     public boolean canEncode(CharSequence sequence) {
         CharBuffer cb;
@@ -275,46 +268,44 @@
     }
 
     /**
-     * Get the <code>Charset</code> which creates this encoder.
+     * Gets the <code>Charset</code> which this encoder uses.
      * 
-     * @return the <code>Charset</code> which creates this encoder
+     * @return the <code>Charset</code> which this encoder uses.
      */
     public final Charset charset() {
         return cs;
     }
 
     /**
-     * This is a facade method for encoding operation.
+     * This is a facade method for the encoding operation.
      * <p>
      * This method encodes the remaining character sequence of the given
      * character buffer into a new byte buffer. This method performs a complete
      * encoding operation, resets at first, then encodes, and flushes at last.
-     * </p>
      * <p>
      * This method should not be invoked if another encode operation is ongoing.
-     * </p>
-     * 
+     *
      * @param in
-     *            the input buffer
-     * @return a new <code>ByteBuffer</code> containing the the bytes produced
-     *         by this encoding operation. The buffer's limit will be the
-     *         position of last byte in buffer, and the position will be zero
+     *            the input buffer.
+     * @return a new <code>ByteBuffer</code> containing the bytes produced by
+     *         this encoding operation. The buffer's limit will be the position
+     *         of the last byte in the buffer, and the position will be zero.
      * @throws IllegalStateException
-     *             if another encoding operation is ongoing
+     *             if another encoding operation is ongoing.
      * @throws MalformedInputException
-     *             if illegal input character sequence for this charset
+     *             if an illegal input character sequence for this charset is
      *             encountered, and the action for malformed error is
      *             {@link CodingErrorAction#REPORT CodingErrorAction.REPORT}
      * @throws UnmappableCharacterException
-     *             if legal but unmappable input character sequence for this
-     *             charset encountered, and the action for unmappable character
-     *             error is
+     *             if a legal but unmappable input character sequence for this
+     *             charset is encountered, and the action for unmappable
+     *             character error is
      *             {@link CodingErrorAction#REPORT CodingErrorAction.REPORT}.
      *             Unmappable means the Unicode character sequence at the input
      *             buffer's current position cannot be mapped to a equivalent
      *             byte sequence.
      * @throws CharacterCodingException
-     *             if other exception happened during the encode operation
+     *             if other exception happened during the encode operation.
      */
     public final ByteBuffer encode(CharBuffer in)
             throws CharacterCodingException {
@@ -390,64 +381,60 @@
      * <p>
      * The buffers' position will be changed with the reading and writing
      * operation, but their limits and marks will be kept intact.
-     * </p>
      * <p>
      * A <code>CoderResult</code> instance will be returned according to
      * following rules:
      * <ul>
      * <li>A {@link CoderResult#malformedForLength(int) malformed input} result
-     * indicates that some malformed input error encountered, and the erroneous
-     * characters start at the input buffer's position and their number can be
-     * got by result's {@link CoderResult#length() length}. This kind of result
-     * can be returned only if the malformed action is
-     * {@link CodingErrorAction#REPORT CodingErrorAction.REPORT}. </li>
+     * indicates that some malformed input error was encountered, and the
+     * erroneous characters start at the input buffer's position and their
+     * number can be got by result's {@link CoderResult#length() length}. This
+     * kind of result can be returned only if the malformed action is
+     * {@link CodingErrorAction#REPORT CodingErrorAction.REPORT}.</li>
      * <li>{@link CoderResult#UNDERFLOW CoderResult.UNDERFLOW} indicates that
-     * as many characters as possible in the input buffer has been encoded. If
+     * as many characters as possible in the input buffer have been encoded. If
      * there is no further input and no characters left in the input buffer then
      * this task is complete. If this is not the case then the client should
      * call this method again supplying some more input characters.</li>
      * <li>{@link CoderResult#OVERFLOW CoderResult.OVERFLOW} indicates that the
      * output buffer has been filled, while there are still some characters
      * remaining in the input buffer. This method should be invoked again with a
-     * non-full output buffer </li>
+     * non-full output buffer.</li>
      * <li>A {@link CoderResult#unmappableForLength(int) unmappable character}
      * result indicates that some unmappable character error was encountered,
      * and the erroneous characters start at the input buffer's position and
      * their number can be got by result's {@link CoderResult#length() length}.
      * This kind of result can be returned only on
-     * {@link CodingErrorAction#REPORT CodingErrorAction.REPORT}. </li>
+     * {@link CodingErrorAction#REPORT CodingErrorAction.REPORT}.</li>
      * </ul>
-     * </p>
      * <p>
-     * The <code>endOfInput</code> parameter indicates that if the invoker can
+     * The <code>endOfInput</code> parameter indicates if the invoker can
      * provider further input. This parameter is true if and only if the
-     * characters in current input buffer are all inputs for this encoding
-     * operation. Note that it is common and won't cause error that the invoker
-     * sets false and then finds no more input available; while it may cause
-     * error that the invoker always sets true in several consecutive
-     * invocations so that any remaining input will be treated as malformed
+     * characters in the current input buffer are all inputs for this encoding
+     * operation. Note that it is common and won't cause an error if the invoker
+     * sets false and then has no more input available, while it may cause an
+     * error if the invoker always sets true in several consecutive invocations.
+     * This would make the remaining input to be treated as malformed input.
      * input.
-     * </p>
      * <p>
-     * This method invokes
+     * This method invokes the
      * {@link #encodeLoop(CharBuffer, ByteBuffer) encodeLoop} method to
-     * implement basic encode logic for specific charset.
-     * </p>
-     * 
+     * implement the basic encode logic for a specific charset.
+     *
      * @param in
-     *            the input buffer
+     *            the input buffer.
      * @param out
-     *            the output buffer
+     *            the output buffer.
      * @param endOfInput
-     *            true if all the input characters have been provided
-     * @return a <code>CoderResult</code> instance indicating the result
+     *            true if all the input characters have been provided.
+     * @return a <code>CoderResult</code> instance indicating the result.
      * @throws IllegalStateException
      *             if the encoding operation has already started or no more
-     *             input needed in this encoding progress.
+     *             input is needed in this encoding process.
      * @throws CoderMalfunctionError
      *             If the {@link #encodeLoop(CharBuffer, ByteBuffer) encodeLoop}
      *             method threw an <code>BufferUnderflowException</code> or
-     *             <code>BufferUnderflowException</code>
+     *             <code>BufferUnderflowException</code>.
      */
     public final CoderResult encode(CharBuffer in, ByteBuffer out,
             boolean endOfInput) {
@@ -501,68 +488,69 @@
     }
 
     /**
-     * Encode characters into bytes. This method is called by
+     * Encodes characters into bytes. This method is called by
      * {@link #encode(CharBuffer, ByteBuffer, boolean) encode}.
-     * 
+     * <p>
      * This method will implement the essential encoding operation, and it won't
      * stop encoding until either all the input characters are read, the output
-     * buffer is filled, or some exception encountered. And then it will return
-     * a <code>CoderResult</code> object indicating the result of current
-     * encoding operation. The rules to construct the <code>CoderResult</code>
-     * is same as the {@link #encode(CharBuffer, ByteBuffer, boolean) encode}.
-     * When exception encountered in the encoding operation, most implementation
-     * of this method will return a relevant result object to
+     * buffer is filled, or some exception is encountered. Then it will
+     * return a <code>CoderResult</code> object indicating the result of the
+     * current encoding operation. The rule to construct the
+     * <code>CoderResult</code> is the same as for
+     * {@link #encode(CharBuffer, ByteBuffer, boolean) encode}. When an
+     * exception is encountered in the encoding operation, most implementations
+     * of this method will return a relevant result object to the
      * {@link #encode(CharBuffer, ByteBuffer, boolean) encode} method, and some
      * performance optimized implementation may handle the exception and
      * implement the error action itself.
-     * 
+     * <p>
      * The buffers are scanned from their current positions, and their positions
      * will be modified accordingly, while their marks and limits will be
      * intact. At most {@link CharBuffer#remaining() in.remaining()} characters
      * will be read, and {@link ByteBuffer#remaining() out.remaining()} bytes
      * will be written.
-     * 
-     * Note that some implementation may pre-scan the input buffer and return
+     * <p>
+     * Note that some implementations may pre-scan the input buffer and return
      * <code>CoderResult.UNDERFLOW</code> until it receives sufficient input.
-     * 
+     * <p>
      * @param in
-     *            the input buffer
+     *            the input buffer.
      * @param out
-     *            the output buffer
-     * @return a <code>CoderResult</code> instance indicating the result
+     *            the output buffer.
+     * @return a <code>CoderResult</code> instance indicating the result.
      */
     protected abstract CoderResult encodeLoop(CharBuffer in, ByteBuffer out);
 
     /**
-     * Flush this encoder.
-     * 
+     * Flushes this encoder.
+     * <p>
      * This method will call {@link #implFlush(ByteBuffer) implFlush}. Some
      * encoders may need to write some bytes to the output buffer when they have
      * read all input characters, subclasses can overridden
      * {@link #implFlush(ByteBuffer) implFlush} to perform writing action.
-     * 
+     * <p>
      * The maximum number of written bytes won't larger than
-     * {@link ByteBuffer#remaining() out.remaining()}. If some encoder want to
-     * write more bytes than output buffer's remaining spaces, then
+     * {@link ByteBuffer#remaining() out.remaining()}. If some encoder wants to
+     * write more bytes than the output buffer's available remaining space, then
      * <code>CoderResult.OVERFLOW</code> will be returned, and this method
-     * must be called again with a byte buffer has more spaces. Otherwise this
-     * method will return <code>CoderResult.UNDERFLOW</code>, which means one
-     * encoding process has been completed successfully.
-     * 
+     * must be called again with a byte buffer that has free space. Otherwise
+     * this method will return <code>CoderResult.UNDERFLOW</code>, which
+     * means one encoding process has been completed successfully.
+     * <p>
      * During the flush, the output buffer's position will be changed
      * accordingly, while its mark and limit will be intact.
      * 
      * @param out
-     *            the given output buffer
+     *            the given output buffer.
      * @return <code>CoderResult.UNDERFLOW</code> or
-     *         <code>CoderResult.OVERFLOW</code>
+     *         <code>CoderResult.OVERFLOW</code>.
      * @throws IllegalStateException
      *             if this encoder hasn't read all input characters during one
      *             encoding process, which means neither after calling
      *             {@link #encode(CharBuffer) encode(CharBuffer)} nor after
      *             calling {@link #encode(CharBuffer, ByteBuffer, boolean) 
-     *             encode(CharBuffer, ByteBuffer, boolean)} with true value for
-     *             the last boolean parameter
+     *             encode(CharBuffer, ByteBuffer, boolean)} with {@code true}
+     *             for the last boolean parameter.
      */
     public final CoderResult flush(ByteBuffer out) {
         if (status != END && status != INIT) {
@@ -576,64 +564,64 @@
     }
 
     /**
-     * Flush this encoder. Default implementation does nothing and always return
-     * <code>CoderResult.UNDERFLOW</code>, and this method can be overridden
-     * if needed.
+     * Flushes this encoder. The default implementation does nothing and always
+     * returns <code>CoderResult.UNDERFLOW</code>; this method can be
+     * overridden if needed.
      * 
      * @param out
-     *            the output buffer
+     *            the output buffer.
      * @return <code>CoderResult.UNDERFLOW</code> or
-     *         <code>CoderResult.OVERFLOW</code>
+     *         <code>CoderResult.OVERFLOW</code>.
      */
     protected CoderResult implFlush(ByteBuffer out) {
         return CoderResult.UNDERFLOW;
     }
 
     /**
-     * Notify that this encoder's <code>CodingErrorAction</code> specified for
-     * malformed input error has been changed. Default implementation does
-     * nothing, and this method can be overridden if needed.
+     * Notifies that this encoder's <code>CodingErrorAction</code> specified
+     * for malformed input error has been changed. The default implementation
+     * does nothing; this method can be overridden if needed.
      * 
      * @param newAction
-     *            The new action
+     *            the new action.
      */
     protected void implOnMalformedInput(CodingErrorAction newAction) {
         // default implementation is empty
     }
 
     /**
-     * Notify that this encoder's <code>CodingErrorAction</code> specified for
-     * unmappable character error has been changed. Default implementation does
-     * nothing, and this method can be overridden if needed.
+     * Notifies that this encoder's <code>CodingErrorAction</code> specified
+     * for unmappable character error has been changed. The default
+     * implementation does nothing; this method can be overridden if needed.
      * 
      * @param newAction
-     *            The new action
+     *            the new action.
      */
     protected void implOnUnmappableCharacter(CodingErrorAction newAction) {
         // default implementation is empty
     }
 
     /**
-     * Notify that this encoder's replacement has been changed. Default
-     * implementation does nothing, and this method can be overridden if needed.
+     * Notifies that this encoder's replacement has been changed. The default
+     * implementation does nothing; this method can be overridden if needed.
      * 
      * @param newReplacement
-     *            the new replacement string
+     *            the new replacement string.
      */
     protected void implReplaceWith(byte[] newReplacement) {
         // default implementation is empty
     }
 
     /**
-     * Reset this encoder's charset related state. Default implementation does
-     * nothing, and this method can be overridden if needed.
+     * Resets this encoder's charset related state. The default implementation
+     * does nothing; this method can be overridden if needed.
      */
     protected void implReset() {
         // default implementation is empty
     }
 
     /**
-     * Check if the given argument is legal as this encoder's replacement byte
+     * Checks if the given argument is legal as this encoder's replacement byte
      * array.
      * 
      * The given byte array is legal if and only if it can be decode into
@@ -642,7 +630,7 @@
      * This method can be overridden for performance improvement.
      * 
      * @param repl
-     *            the given byte array to be checked
+     *            the given byte array to be checked.
      * @return true if the the given argument is legal as this encoder's
      *         replacement byte array.
      */
@@ -665,39 +653,39 @@
     }
 
     /**
-     * Gets this encoder's <code>CodingErrorAction</code> when malformed input
-     * occurred during encoding process.
+     * Gets this encoder's <code>CodingErrorAction</code> when a malformed
+     * input error occurred during the encoding process.
      * 
-     * @return this encoder's <code>CodingErrorAction</code> when malformed
-     *         input occurred during encoding process.
+     * @return this encoder's <code>CodingErrorAction</code> when a malformed
+     *         input error occurred during the encoding process.
      */
     public CodingErrorAction malformedInputAction() {
         return malformAction;
     }
 
     /**
-     * Get the maximum number of bytes which can be created by this encoder for
-     * one input character, must be positive
+     * Gets the maximum number of bytes which can be created by this encoder for
+     * one input character, must be positive.
      * 
      * @return the maximum number of bytes which can be created by this encoder
-     *         for one input character, must be positive
+     *         for one input character, must be positive.
      */
     public final float maxBytesPerChar() {
         return maxBytes;
     }
 
     /**
-     * Set this encoder's action on malformed input error.
+     * Sets this encoder's action on malformed input error.
      * 
      * This method will call the
      * {@link #implOnMalformedInput(CodingErrorAction) implOnMalformedInput}
      * method with the given new action as argument.
      * 
      * @param newAction
-     *            the new action on malformed input error
-     * @return this encoder
+     *            the new action on malformed input error.
+     * @return this encoder.
      * @throws IllegalArgumentException
-     *             if the given newAction is null
+     *             if the given newAction is null.
      */
     public final CharsetEncoder onMalformedInput(CodingErrorAction newAction) {
         if (null == newAction) {
@@ -710,17 +698,17 @@
     }
 
     /**
-     * Set this encoder's action on unmappable character error.
+     * Sets this encoder's action on unmappable character error.
      * 
      * This method will call the
      * {@link #implOnUnmappableCharacter(CodingErrorAction) implOnUnmappableCharacter}
      * method with the given new action as argument.
      * 
      * @param newAction
-     *            the new action on unmappable character error
-     * @return this encoder
+     *            the new action on unmappable character error.
+     * @return this encoder.
      * @throws IllegalArgumentException
-     *             if the given newAction is null
+     *             if the given newAction is null.
      */
     public final CharsetEncoder onUnmappableCharacter(
             CodingErrorAction newAction) {
@@ -734,33 +722,31 @@
     }
 
     /**
-     * Get the replacement byte array, which is never null or empty, and it is
-     * legal
+     * Gets the replacement byte array, which is never null or empty.
      * 
-     * @return the replacement byte array, cannot be null or empty, and it is
-     *         legal
+     * @return the replacement byte array, cannot be null or empty.
      */
     public final byte[] replacement() {
         return replace;
     }
 
     /**
-     * Set new replacement value.
+     * Sets the new replacement value.
      * 
      * This method first checks the given replacement's validity, then changes
-     * the replacement value, and at last calls
+     * the replacement value and finally calls the
      * {@link #implReplaceWith(byte[]) implReplaceWith} method with the given
      * new replacement as argument.
      * 
      * @param replacement
      *            the replacement byte array, cannot be null or empty, its
-     *            length cannot larger than <code>maxBytesPerChar</code>, and
-     *            must be legal replacement, which can be justified by
-     *            <code>isLegalReplacement(byte[] repl)</code>
-     * @return this encoder
+     *            length cannot be larger than <code>maxBytesPerChar</code>,
+     *            and it must be legal replacement, which can be justified by
+     *            calling <code>isLegalReplacement(byte[] repl)</code>.
+     * @return this encoder.
      * @throws IllegalArgumentException
      *             if the given replacement cannot satisfy the requirement
-     *             mentioned above
+     *             mentioned above.
      */
     public final CharsetEncoder replaceWith(byte[] replacement) {
         if (null == replacement || 0 == replacement.length
@@ -775,11 +761,11 @@
     }
 
     /**
-     * Reset this encoder. This method will reset internal status, and then call
-     * <code>implReset()</code> to reset any status related to specific
-     * charset.
+     * Resets this encoder. This method will reset the internal status and then
+     * calla <code>implReset()</code> to reset any status related to the
+     * specific charset.
      * 
-     * @return this encoder
+     * @return this encoder.
      */
     public final CharsetEncoder reset() {
         status = INIT;

Modified: harmony/enhanced/classlib/trunk/modules/nio_char/src/main/java/java/nio/charset/CoderMalfunctionError.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio_char/src/main/java/java/nio/charset/CoderMalfunctionError.java?rev=769094&r1=769093&r2=769094&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio_char/src/main/java/java/nio/charset/CoderMalfunctionError.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio_char/src/main/java/java/nio/charset/CoderMalfunctionError.java Mon Apr 27 18:39:23 2009
@@ -18,7 +18,8 @@
 package java.nio.charset;
 
 /**
- * Errors thrown when the encoder/decoder is malfunctioning.
+ * A {@code CoderMalfunctionError} is thrown when the encoder/decoder is
+ * malfunctioning.
  */
 public class CoderMalfunctionError extends Error {
 
@@ -29,10 +30,10 @@
     private static final long serialVersionUID = -1151412348057794301L;
 
     /**
-     * Constructs an instance of this error.
+     * Constructs a new {@code CoderMalfunctionError}.
      * 
      * @param ex
-     *            the original exception thrown by the encoder/decoder
+     *            the original exception thrown by the encoder/decoder.
      */
     public CoderMalfunctionError(Exception ex) {
         super(ex);



Mime
View raw message