Name: sdR10048 Date: 09/25/2002


JDK1.4 doc for 3 constructors:
java.awt.event.ActionEvent(Object source, int id, String command)
java.awt.event.ActionEvent(Object source, int id, String command, int modifiers)
java.awt.event.ActionEvent(Object source, int id, String command, long when, int modifiers)
says:
> public ActionEvent(Object source,
> int id,
> String command,
> long when,
> int modifiers)
>
> Constructs an ActionEvent object with the specified modifier keys and
> timestamp.
>
> Note that passing in an invalid id results in unspecified behavior.
>
> Parameters:
> source - the object that originated the event
> id - an integer that identifies the event
> command - a string that may specify a command (possibly one of
> several) associated with the event
> when - the time the event occurred
> modifiers - the modifier keys held down during this action
> Since:
> 1.4
It is not quite clear how an 'invalid id' looks like. Should be
stated explicitly.
See: http://java.sun.com/j2se/javadoc/writingapispecs/index.html#method
Need for jck test development.
======================================================================

Name: rmT116609 Date: 05/23/2003


A DESCRIPTION OF THE PROBLEM :
In the API documentation for java.awt.ActionEvent constructors, the specification
of id parameter is incomplete. It doesn't define what legal values are or how
the id value is used (or refer the reader to documentation that does).




EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
At a high level: The documentation should describe, or should point the reader
to a description of, the contract for the "id" parameter (what legal values are,
and, ideally, how the ID value is used).

Concretely: The parameter (or constructor or at least class) description
should either refer the reader to the specification of ID parameter
values in some other class or interface's JavaDoc page, or should describe
the contract for the ID parameter.


ACTUAL -
The three constructor descriptions say only:

   ...passing in an invalid id results in unspecified behavior.
   ...
       id - an integer that identifies the event

The class description text doesn't say anything about event IDs.



URL OF FAULTY DOCUMENTATION :
http://java.sun.com/j2se/1.4.2/docs/api/java/awt/event/ActionEvent.html#ActionEvent(java.lang.Object,%20int,%20java.lang.String)
(Review ID: 186380)
======================================================================