Name: bsC130419 Date: 06/26/2001


java version "1.3.0"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.3.0-C)
Java HotSpot(TM) Client VM (build 1.3.0-C, mixed mode)


The method documentation for URLDecoder.decode(String) is poorly written and
unclear.

It says:

  Decodes a "x-www-form-urlencoded" to a String.


1. "x-www-form-urlencoded" is a partial name of a MIME type, and it's not
a thing, so how can you refer to "a 'x-www-form-urlencoded'"? That makes
no sense.


2. URLEncoder.encode(String) says:

  Translates a string into x-www-form-urlencoded format.

Why doesn't the decode method at least say something similar, like:

  Decodes a string from x-www-form-urlencoded format.


3. It would help if references used full name of the MIME media type
("application/x-www-form-urlencoded"), and mentioned that it was a MIME
type.

4. (It's a little confusing that the URL encoder/decoder classes refer
to MIME-type application/x-www-form-urlencoded when the specification
of URLs (RFC 2396, Uniform Resource Identifiers (URI): Generic Syntax
(http://sunsite.dk/RFC/rfc/rfc2396.html)) never refers to it in its
defining of encoding characters in URLs.

Maybe the documentation should mention that the methods are for
encoding/decoding information stored in _portions_ of URLs, but not
for processing whole URLs. Maybe it should refer to the relevent RFCs.)


5. It would be helpful if URLDecoder.decode(String) referred to
URLEncoder.encode(String) and vice versa.


(Review ID: 126311)
======================================================================