P4 Description
Name: rmT116609 Date: 08/23/2004
A DESCRIPTION OF THE PROBLEM :
The documentation for the "java" command, at least the Windows version of
the HTML page at the above URL as of 2004-08-23, has a few problems:
1. It says "para meter" (note the extra space).
2. Where it says:
The method declaration must look like the following:
public static void main(String args[])
the text is unclear and over-constraining.
It is unclear in which ways the method declaration must be like the given
code.
It is over-constraining in that it could imply that:
- the parameter name must be "args"
- the method must not be declared "final"
- the method must not throw any exceptions (one of your implementors of
the J2EE 1.3 RI client application launcher thought that main(...) couldn't
throw checked exceptions (the launcher wouldn't recognize a main(...)
method with a throws clause))
- the non-recommended form "String args[]" must be used instead of the
common and recommended form "String[] args"
- etc.
Saying something "must look like" something else is inappropriate in a
specification unless how they much be alike is spelled out.
I assume that showing the declaration of a main(...) method is to give an
example to make it easier for the reader to recognize what is needed.
Instead of saying ""must look like," wouldn't it be better to say something
like "for example" and then give the example?
Actually, where's the Java definition of a main class? Is that concept and
the details defined by JLS or are they just defined by the "java" command?
(Perhaps the "java" command documentation could also point to wherever
the primary definition lives.)
3. (Minor) Wouldn't using the form "String[] args" be better than "String
args[]"? (Isn't the second form discouraged and the first form recommended
and more common (and clearer, grouping the type information together)?)
4. It says "argume nt" (another extra space character).
URL OF FAULTY DOCUMENTATION :
http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/java.html
(Incident Review ID: 300559)
======================================================================