Name: skT88420 Date: 12/03/99


Independent of version: documentation bug


The javadoc for the class DataOutputStream is incomplete.

For example the writeUTF method does not document the limitation
in string size as documented in the JLS. As a result, developers are
surprised to receive an IOException that they can interprete as a network
error, when the trouble is only that the string length was exceeded. It
happened to me and it's a time consumming debugging activity!
At least the throws clause should document the UTFDataFormatError when
"the total number of bytes needed to represent all the characters of s is
calculated." Then a method should be provided to let users of the class
DataOutputStream know if they string is larger than the accepted size
without waiting for the exception to occur or duplicate the code in
DataOutputStream.writeUTF.

Check it:
http://java.sun.com/products/jdk/1.2/docs/api/java/io/DataOutputStream.html#writeUTF(java.lang.String)

Suggestion: reproduce the documentation from the JLS section 22.2.14
(that very throughout!) into the javadoc.
Note: this bug is obviously also in 1.1 code base (1.1.8)
(Review ID: 98590)
======================================================================