The class specification for java.nio.CharsetDecoder ends abruptly with the
sentence fragment "The substitution is a string that". Similarly, the class
specification for java.nio.CharsetEncoder ends with the fragment "The
substitution is a byte array that".

The CharsetDecoder specification should end with the following text:

 * <p> How decoding errors are handled depends upon whether the
 * <i>substitution</i> is defined. The substitution is a string that is
 * initially set to <tt>"&#92;uFFFD"</tt>; its value may be changed via the
 * {@link #substitute(java.lang.String) substitute} method. If the
 * substitution is defined then it is copied to the output buffer each time a
 * decoding error occurs. If the substitution is not defined then an
 * appropriate exception, either {@link MalformedInputException} or {@link
 * UnmappableCharacterException}, is thrown when such an error occurs.
 *
 * <p> This class is designed to handle all of the bookkeeping required by the
 * decoding process. A decoder for a specific charset, which is a concrete
 * subclass of this class, need only implement the abstract {@link #decodeStep
 * decodeStep} method, which encapsulates a basic decoding step. A subclass
 * that maintains internal state should, additionally, override the {@link
 * #flush flush} and {@link #reset reset} methods. </p>

The CharsetEncoder specification should end with the following two paragraphs:

 * <p> How encoding errors are handled depends upon whether the
 * <i>substitution</i> is defined. The substitution is a byte array that is
 * initially set to the encoder's default substitution, which is often (but not
 * always) the byte
 * array&nbsp;<tt>{</tt>&nbsp;<tt>(byte)'?'</tt>&nbsp;<tt>}</tt>; its value may
 * be changed via the {@link #substitute(byte[]) substitute} method. If the
 * substitution is defined then it is copied to the output buffer each time an
 * encoding error occurs. If the substitution is not defined then an
 * appropriate exception, either {@link MalformedInputException} or {@link
 * UnmappableCharacterException}, is thrown when such an error occurs.
 *
 * <p> This class is designed to handle all of the bookkeeping required by the
 * encoding process. An encoder for a specific charset, which is a concrete
 * subclass of this class, need only implement the abstract {@link #encodeStep
 * encodeStep} method, which encapsulates a basic encoding step. A subclass
 * that maintains internal state should, additionally, override the {@link
 * #flush flush} and {@link #reset reset} methods. </p>

The text is missing due to a minor oversight in the code that generates the
source code for these classes from a shared template.

-- mr@eng 2000/12/19