6520716: event classes lack info about parameters

Summary: clarify allowed values for event constructors
Reviewed-by: son, denis

src/share/classes/java/awt/dnd/DragGestureEvent.java

 /*
- * Copyright 1998-2006 Sun Microsystems, Inc.  All Rights Reserved.
+ * Copyright 1998-2008 Sun Microsystems, Inc.  All Rights Reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -55,9 +55,19 @@ import java.io.ObjectOutputStream;
  * platform dependent drag initiating gesture has occurred
  * on the <code>Component</code> that it is tracking.
  *
+ * The {@code action} field of any {@code DragGestureEvent} instance should take one of the following
+ * values:
+ * <ul>
+ * <li> {@code DnDConstants.ACTION_COPY}
+ * <li> {@code DnDConstants.ACTION_MOVE}
+ * <li> {@code DnDConstants.ACTION_LINK}
+ * </ul>
+ * Assigning the value different from listed above will cause an unspecified behavior.
+ *
  * @see java.awt.dnd.DragGestureRecognizer
  * @see java.awt.dnd.DragGestureListener
  * @see java.awt.dnd.DragSource
+ * @see java.awt.dnd.DnDConstants
  */
 
 public class DragGestureEvent extends EventObject {
@@ -65,19 +75,25 @@ public class DragGestureEvent extends EventObject {
     private static final long serialVersionUID = 9080172649166731306L;
 
     /**
-     * Constructs a <code>DragGestureEvent</code> given the
-     * <code>DragGestureRecognizer</code> firing this event,
-     * an <code>int</code> representing
-     * the user's preferred action, a <code>Point</code>
-     * indicating the origin of the drag, and a <code>List</code>
-     * of events that comprise the gesture.
+     * Constructs a <code>DragGestureEvent</code> object given by the
+     * <code>DragGestureRecognizer</code> instance firing this event,
+     * an {@code act} parameter representing
+     * the user's preferred action, an {@code ori} parameter
+     * indicating the origin of the drag, and a {@code List} of
+     * events that comprise the gesture({@code evs} parameter).
      * <P>
      * @param dgr The <code>DragGestureRecognizer</code> firing this event
-     * @param act The the user's preferred action
+     * @param act The user's preferred action.
+     *            For information on allowable values, see
+     *            the class description for {@link DragGestureEvent}
      * @param ori The origin of the drag
      * @param evs The <code>List</code> of events that comprise the gesture
      * <P>
-     * @throws IllegalArgumentException if input parameters are {@code null}
+     * @throws IllegalArgumentException if any parameter equals {@code null}
+     * @throws IllegalArgumentException if the act parameter does not comply with
+     *                                  the values given in the class
+     *                                  description for {@link DragGestureEvent}
+     * @see java.awt.dnd.DnDConstants
      */
 
     public DragGestureEvent(DragGestureRecognizer dgr, int act, Point ori,

src/share/classes/java/awt/dnd/DropTargetEvent.java

@@ -45,10 +45,13 @@ public class DropTargetEvent extends java.util.EventObject {
     private static final long serialVersionUID = 2821229066521922993L;
 
     /**
-     * Construct a <code>DropTargetEvent</code> with
-     * a specified <code>DropTargetContext</code>.
+     * Construct a <code>DropTargetEvent</code> object with
+     * the specified <code>DropTargetContext</code>.
      * <P>
-     * @param dtc the <code>DropTargetContext</code>
+     * @param dtc The <code>DropTargetContext</code>
+     * @throws NullPointerException if {@code dtc} equals {@code null}.
+     * @see #getSource()
+     * @see #getDropTargetContext()
      */
 
     public DropTargetEvent(DropTargetContext dtc) {

src/share/classes/java/awt/event/ActionEvent.java

 /*
- * Copyright 1996-2006 Sun Microsystems, Inc.  All Rights Reserved.
+ * Copyright 1996-2008 Sun Microsystems, Inc.  All Rights Reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -45,6 +45,10 @@ import java.awt.Event;
  * is therefore spared the details of processing individual mouse movements
  * and mouse clicks, and can instead process a "meaningful" (semantic)
  * event like "button pressed".
+ * <p>
+ * An unspecified behavior will be caused if the {@code id} parameter
+ * of any particular {@code ActionEvent} instance is not
+ * in the range from {@code ACTION_FIRST} to {@code ACTION_LAST}.
  *
  * @see ActionListener
  * @see <a href="http://java.sun.com/docs/books/tutorial/post1.0/ui/eventmodel.html">Tutorial: Java 1.1 Event Model</a>
@@ -134,18 +138,22 @@ public class ActionEvent extends AWTEvent {
     /**
      * Constructs an <code>ActionEvent</code> object.
      * <p>
-     * Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      * A <code>null</code> <code>command</code> string is legal,
      * but not recommended.
      *
-     * @param source  the object that originated the event
-     * @param id      an integer that identifies the event
-     * @param command a string that may specify a command (possibly one
+     * @param source  The object that originated the event
+     * @param id      An integer that identifies the event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link ActionEvent}
+     * @param command A string that may specify a command (possibly one
      *                of several) associated with the event
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getSource()
+     * @see #getID()
+     * @see #getActionCommand()
      */
     public ActionEvent(Object source, int id, String command) {
         this(source, id, command, 0);
@@ -154,19 +162,27 @@ public class ActionEvent extends AWTEvent {
     /**
      * Constructs an <code>ActionEvent</code> object with modifier keys.
      * <p>
-     * Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      * A <code>null</code> <code>command</code> string is legal,
      * but not recommended.
      *
-     * @param source    the object that originated the event
-     * @param id        an integer that identifies the event
-     * @param command   a string that may specify a command (possibly one
-     *                  of several) associated with the event
-     * @param modifiers the modifier keys held down during this action
+     * @param source  The object that originated the event
+     * @param id      An integer that identifies the event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link ActionEvent}
+     * @param command A string that may specify a command (possibly one
+     *                of several) associated with the event
+     * @param modifiers The modifier keys down during event
+     *                  (shift, ctrl, alt, meta).
+     *                  Passing negative parameter is not recommended.
+     *                  Zero value means that no modifiers were passed
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getSource()
+     * @see #getID()
+     * @see #getActionCommand()
+     * @see #getModifiers()
      */
     public ActionEvent(Object source, int id, String command, int modifiers) {
         this(source, id, command, 0, modifiers);
@@ -176,20 +192,31 @@ public class ActionEvent extends AWTEvent {
      * Constructs an <code>ActionEvent</code> object with the specified
      * modifier keys and timestamp.
      * <p>
-     * Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      * A <code>null</code> <code>command</code> string is legal,
      * but not recommended.
      *
-     * @param source    the object that originated the event
-     * @param id        an integer that identifies the event
-     * @param command   a string that may specify a command (possibly one
-     *                  of several) associated with the event
-     * @param when      the time the event occurred
-     * @param modifiers the modifier keys held down during this action
+     * @param source    The object that originated the event
+     * @param id      An integer that identifies the event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link ActionEvent}
+     * @param command A string that may specify a command (possibly one
+     *                of several) associated with the event
+     * @param modifiers The modifier keys down during event
+     *                  (shift, ctrl, alt, meta).
+     *                  Passing negative parameter is not recommended.
+     *                  Zero value means that no modifiers were passed
+     * @param when   A long that gives the time the event occurred.
+     *               Passing negative or zero value
+     *               is not recommended
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getSource()
+     * @see #getID()
+     * @see #getActionCommand()
+     * @see #getModifiers()
+     * @see #getWhen()
      *
      * @since 1.4
      */

src/share/classes/java/awt/event/AdjustmentEvent.java

@@ -29,7 +29,25 @@ import java.awt.Adjustable;
 import java.awt.AWTEvent;
 
 /**
- * The adjustment event emitted by Adjustable objects.
+ * The adjustment event emitted by Adjustable objects like
+ * {@link java.awt.Scrollbar} and {@link java.awt.ScrollPane}.
+ * When the user changes the value of the scrolling component,
+ * it receives an instance of {@code AdjustmentEvent}.
+ * <p>
+ * An unspecified behavior will be caused if the {@code id} parameter
+ * of any particular {@code AdjustmentEvent} instance is not
+ * in the range from {@code ADJUSTMENT_FIRST} to {@code ADJUSTMENT_LAST}.
+ * <p>
+ * The {@code type} of any {@code AdjustmentEvent} instance takes one of the following
+ * values:
+ *                     <ul>
+ *                     <li> {@code UNIT_INCREMENT}
+ *                     <li> {@code UNIT_DECREMENT}
+ *                     <li> {@code BLOCK_INCREMENT}
+ *                     <li> {@code BLOCK_DECREMENT}
+ *                     <li> {@code TRACK}
+ *                     </ul>
+ * Assigning the value different from listed above will cause an unspecified behavior.
  * @see java.awt.Adjustable
  * @see AdjustmentListener
  *
@@ -130,17 +148,24 @@ public class AdjustmentEvent extends AWTEvent {
      * Constructs an <code>AdjustmentEvent</code> object with the
      * specified <code>Adjustable</code> source, event type,
      * adjustment type, and value.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior.  This method throws an
+     * <p> This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source the <code>Adjustable</code> object where the
+     * @param source The <code>Adjustable</code> object where the
      *               event originated
-     * @param id     the event type
-     * @param type   the adjustment type
-     * @param value  the current value of the adjustment
+     * @param id     An integer indicating the type of event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link AdjustmentEvent}
+     * @param type   An integer indicating the adjustment type.
+     *                     For information on allowable values, see
+     *                     the class description for {@link AdjustmentEvent}
+     * @param value  The current value of the adjustment
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getSource()
+     * @see #getID()
+     * @see #getAdjustmentType()
+     * @see #getValue()
      */
     public AdjustmentEvent(Adjustable source, int id, int type, int value) {
         this(source, id, type, value, false);
@@ -149,22 +174,29 @@ public class AdjustmentEvent extends AWTEvent {
     /**
      * Constructs an <code>AdjustmentEvent</code> object with the
      * specified Adjustable source, event type, adjustment type, and value.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior.  This method throws an
+     * <p> This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
-
      *
-     * @param source the <code>Adjustable</code> object where the
+     * @param source The <code>Adjustable</code> object where the
      *               event originated
-     * @param id     the event type
-     * @param type   the adjustment type
-     * @param value  the current value of the adjustment
-     * @param isAdjusting <code>true</code> if the event is one
+     * @param id     An integer indicating the type of event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link AdjustmentEvent}
+     * @param type   An integer indicating the adjustment type.
+     *                     For information on allowable values, see
+     *                     the class description for {@link AdjustmentEvent}
+     * @param value  The current value of the adjustment
+     * @param isAdjusting A boolean that equals <code>true</code> if the event is one
      *               of a series of multiple adjusting events,
      *               otherwise <code>false</code>
      * @throws IllegalArgumentException if <code>source</code> is null
      * @since 1.4
+     * @see #getSource()
+     * @see #getID()
+     * @see #getAdjustmentType()
+     * @see #getValue()
+     * @see #getValueIsAdjusting()
      */
     public AdjustmentEvent(Adjustable source, int id, int type, int value, boolean isAdjusting) {
         super(source, id);

src/share/classes/java/awt/event/ComponentEvent.java

@@ -52,6 +52,10 @@ import java.awt.Rectangle;
  * (<code>ComponentAdapter</code> objects implement the
  * <code>ComponentListener</code> interface.) Each such listener object
  * gets this <code>ComponentEvent</code> when the event occurs.
+ * <p>
+ * An unspecified behavior will be caused if the {@code id} parameter
+ * of any particular {@code ComponentEvent} instance is not
+ * in the range from {@code COMPONENT_FIRST} to {@code COMPONENT_LAST}.
  *
  * @see ComponentAdapter
  * @see ComponentListener
@@ -99,14 +103,17 @@ public class ComponentEvent extends AWTEvent {
 
     /**
      * Constructs a <code>ComponentEvent</code> object.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p> This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source the <code>Component</code> that originated the event
-     * @param id     an integer indicating the type of event
+     * @param source The <code>Component</code> that originated the event
+     * @param id     An integer indicating the type of event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link ComponentEvent}
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getComponent()
+     * @see #getID()
      */
     public ComponentEvent(Component source, int id) {
         super(source, id);

src/share/classes/java/awt/event/ContainerEvent.java

@@ -45,6 +45,10 @@ import java.awt.Component;
  * (<code>ContainerAdapter</code> objects implement the
  * <code>ContainerListener</code> interface.) Each such listener object
  * gets this <code>ContainerEvent</code> when the event occurs.
+ * <p>
+ * An unspecified behavior will be caused if the {@code id} parameter
+ * of any particular {@code ContainerEvent} instance is not
+ * in the range from {@code CONTAINER_FIRST} to {@code CONTAINER_LAST}.
  *
  * @see ContainerAdapter
  * @see ContainerListener
@@ -92,16 +96,20 @@ public class ContainerEvent extends ComponentEvent {
 
     /**
      * Constructs a <code>ContainerEvent</code> object.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p> This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source the <code>Component</code> object (container)
+     * @param source The <code>Component</code> object (container)
      *               that originated the event
-     * @param id     an integer indicating the type of event
+     * @param id     An integer indicating the type of event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link ContainerEvent}
      * @param child  the component that was added or removed
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getContainer()
+     * @see #getID()
+     * @see #getChild()
      */
     public ContainerEvent(Component source, int id, Component child) {
         super(source, id);

src/share/classes/java/awt/event/FocusEvent.java

@@ -50,6 +50,10 @@ import sun.awt.SunToolkit;
  * reactivated. Both permanent and temporary focus events are delivered using
  * the FOCUS_GAINED and FOCUS_LOST event ids; the level may be distinguished in
  * the event using the isTemporary() method.
+ * <p>
+ * An unspecified behavior will be caused if the {@code id} parameter
+ * of any particular {@code FocusEvent} instance is not
+ * in the range from {@code FOCUS_FIRST} to {@code FOCUS_LAST}.
  *
  * @see FocusAdapter
  * @see FocusListener
@@ -121,18 +125,23 @@ public class FocusEvent extends ComponentEvent {
      * application, with a Java application in a different VM,
      * or with no other <code>Component</code>, then the opposite
      * <code>Component</code> is <code>null</code>.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p> This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source     the <code>Component</code> that originated the event
-     * @param id         <code>FOCUS_GAINED</code> or <code>FOCUS_LOST</code>
-     * @param temporary  <code>true</code> if the focus change is temporary;
+     * @param source     The <code>Component</code> that originated the event
+     * @param id         An integer indicating the type of event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link FocusEvent}
+     * @param temporary  Equals <code>true</code> if the focus change is temporary;
      *                   <code>false</code> otherwise
-     * @param opposite   the other Component involved in the focus change,
+     * @param opposite   The other Component involved in the focus change,
      *                   or <code>null</code>
-     * @throws IllegalArgumentException if <code>source</code> is null
+     * @throws IllegalArgumentException if <code>source</code> equals {@code null}
+     * @see #getSource()
+     * @see #getID()
+     * @see #isTemporary()
+     * @see #getOppositeComponent()
      * @since 1.4
      */
     public FocusEvent(Component source, int id, boolean temporary,
@@ -145,16 +154,20 @@ public class FocusEvent extends ComponentEvent {
     /**
      * Constructs a <code>FocusEvent</code> object and identifies
      * whether or not the change is temporary.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p> This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source    the <code>Component</code> that originated the event
-     * @param id        an integer indicating the type of event
-     * @param temporary <code>true</code> if the focus change is temporary;
+     * @param source    The <code>Component</code> that originated the event
+     * @param id        An integer indicating the type of event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link FocusEvent}
+     * @param temporary Equals <code>true</code> if the focus change is temporary;
      *                  <code>false</code> otherwise
-     * @throws IllegalArgumentException if <code>source</code> is null
+     * @throws IllegalArgumentException if <code>source</code> equals {@code null}
+     * @see #getSource()
+     * @see #getID()
+     * @see #isTemporary()
      */
     public FocusEvent(Component source, int id, boolean temporary) {
         this(source, id, temporary, null);
@@ -163,14 +176,17 @@ public class FocusEvent extends ComponentEvent {
     /**
      * Constructs a <code>FocusEvent</code> object and identifies it
      * as a permanent change in focus.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p> This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source    the <code>Component</code> that originated the event
-     * @param id        an integer indicating the type of event
-     * @throws IllegalArgumentException if <code>source</code> is null
+     * @param source    The <code>Component</code> that originated the event
+     * @param id        An integer indicating the type of event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link FocusEvent}
+     * @throws IllegalArgumentException if <code>source</code> equals {@code null}
+     * @see #getSource()
+     * @see #getID()
      */
     public FocusEvent(Component source, int id) {
         this(source, id, false);

src/share/classes/java/awt/event/HierarchyEvent.java

 /*
- * Copyright 1999-2004 Sun Microsystems, Inc.  All Rights Reserved.
+ * Copyright 1999-2008 Sun Microsystems, Inc.  All Rights Reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -31,7 +31,7 @@ import java.awt.Container;
 
 /**
  * An event which indicates a change to the <code>Component</code>
- * hierarchy to which a <code>Component</code> belongs.
+ * hierarchy to which <code>Component</code> belongs.
  * <ul>
  * <li>Hierarchy Change Events (HierarchyListener)
  *     <ul>
@@ -58,16 +58,30 @@ import java.awt.Container;
  * Container is added, removed, moved, or resized, and passed down the
  * hierarchy. It is also generated by a Component object when that object's
  * <code>addNotify</code>, <code>removeNotify</code>, <code>show</code>, or
- * <code>hide</code> method is called. ANCESTOR_MOVED and ANCESTOR_RESIZED
+ * <code>hide</code> method is called. The {@code ANCESTOR_MOVED} and
+ * {@code ANCESTOR_RESIZED}
  * events are dispatched to every <code>HierarchyBoundsListener</code> or
  * <code>HierarchyBoundsAdapter</code> object which registered to receive
  * such events using the Component's <code>addHierarchyBoundsListener</code>
  * method. (<code>HierarchyBoundsAdapter</code> objects implement the <code>
- * HierarchyBoundsListener</code> interface.) HIERARCHY_CHANGED events are
+ * HierarchyBoundsListener</code> interface.) The {@code HIERARCHY_CHANGED} events are
  * dispatched to every <code>HierarchyListener</code> object which registered
  * to receive such events using the Component's <code>addHierarchyListener
  * </code> method. Each such listener object gets this <code>HierarchyEvent
  * </code> when the event occurs.
+ * <p>
+ * An unspecified behavior will be caused if the {@code id} parameter
+ * of any particular {@code HierarchyEvent} instance is not
+ * in the range from {@code HIERARCHY_FIRST} to {@code HIERARCHY_LAST}.
+ * <br>
+ * The {@code changeFlags} parameter of any {@code HierarchyEvent} instance takes one of the following
+ * values:
+ * <ul>
+ * <li> {@code HierarchyEvent.PARENT_CHANGED}
+ * <li> {@code HierarchyEvent.DISPLAYABILITY_CHANGED}
+ * <li> {@code HierarchyEvent.SHOWING_CHANGED}
+ * </ul>
+ * Assigning the value different from listed above will cause unspecified behavior.
  *
  * @author      David Mendenhall
  * @see         HierarchyListener
@@ -108,20 +122,20 @@ public class HierarchyEvent extends AWTEvent {
     public static final int HIERARCHY_LAST = ANCESTOR_RESIZED;
 
     /**
-     * Indicates that the <code>HIERARCHY_CHANGED</code> event
+     * A change flag indicates that the <code>HIERARCHY_CHANGED</code> event
      * was generated by a reparenting operation.
      */
     public static final int PARENT_CHANGED = 0x1;
 
     /**
-     * Indicates that the <code>HIERARCHY_CHANGED</code> event
-     * was generated due to a change in the displayability
-     * of the hierarchy.  To discern the
-     * current displayability of the hierarchy, call
-     * <code>Component.isDisplayable</code>. Displayability changes occur
-     * in response to explicit or implicit calls to
+     * A change flag indicates that the <code>HIERARCHY_CHANGED</code> event
+     * was generated due to the changing of the hierarchy displayability.
+     * To discern the
+     * current displayability of the hierarchy, call the
+     * <code>Component.isDisplayable</code> method. Displayability changes occur
+     * in response to explicit or implicit calls of the
      * <code>Component.addNotify</code> and
-     * <code>Component.removeNotify</code>.
+     * <code>Component.removeNotify</code> methods.
      *
      * @see java.awt.Component#isDisplayable()
      * @see java.awt.Component#addNotify()
@@ -130,15 +144,15 @@ public class HierarchyEvent extends AWTEvent {
     public static final int DISPLAYABILITY_CHANGED = 0x2;
 
     /**
-     * Indicates that the <code>HIERARCHY_CHANGED</code> event
-     * was generated due to a change in the showing state
-     * of the hierarchy. To discern the
-     * current showing state of the hierarchy, call
-     * <code>Component.isShowing</code>. Showing state changes occur
+     * A change flag indicates that the <code>HIERARCHY_CHANGED</code> event
+     * was generated due to the changing of the hierarchy showing state.
+     * To discern the
+     * current showing state of the hierarchy, call the
+     * <code>Component.isShowing</code> method. Showing state changes occur
      * when either the displayability or visibility of the
      * hierarchy occurs. Visibility changes occur in response to explicit
-     * or implicit calls to <code>Component.show</code> and
-     * <code>Component.hide</code>.
+     * or implicit calls of the <code>Component.show</code> and
+     * <code>Component.hide</code> methods.
      *
      * @see java.awt.Component#isShowing()
      * @see java.awt.Component#addNotify()
@@ -155,20 +169,26 @@ public class HierarchyEvent extends AWTEvent {
     /**
      * Constructs an <code>HierarchyEvent</code> object to identify a
      * change in the <code>Component</code> hierarchy.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p>This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source          the <code>Component</code> object that
+     * @param source          The <code>Component</code> object that
      *                        originated the event
-     * @param id              an integer indicating the type of event
-     * @param changed         the <code>Component</code> at the top of
+     * @param id              An integer indicating the type of event.
+     *                        For information on allowable values, see
+     *                        the class description for {@link HierarchyEvent}
+     * @param changed         The <code>Component</code> at the top of
      *                        the hierarchy which was changed
-     * @param changedParent   the parent of <code>changed</code>; this
+     * @param changedParent   The parent of the <code>changed</code> component.
+     *                        This
      *                        may be the parent before or after the
      *                        change, depending on the type of change
-     * @throws IllegalArgumentException if <code>source</code> is null
+     * @throws IllegalArgumentException if <code>source</code> is {@code null}
+     * @see #getSource()
+     * @see #getID()
+     * @see #getChanged()
+     * @see #getChangedParent()
      */
     public HierarchyEvent(Component source, int id, Component changed,
                           Container changedParent) {
@@ -180,23 +200,32 @@ public class HierarchyEvent extends AWTEvent {
     /**
      * Constructs an <code>HierarchyEvent</code> object to identify
      * a change in the <code>Component</code> hierarchy.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p> This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source          the <code>Component</code> object that
+     * @param source          The <code>Component</code> object that
      *                        originated the event
-     * @param id              an integer indicating the type of event
-     * @param changed         the <code>Component</code> at the top
+     * @param id              An integer indicating the type of event.
+     *                        For information on allowable values, see
+     *                        the class description for {@link HierarchyEvent}
+     * @param changed         The <code>Component</code> at the top
      *                        of the hierarchy which was changed
-     * @param changedParent   the parent of <code>changed</code>; this
+     * @param changedParent   The parent of the <code>changed</code> component.
+     *                        This
      *                        may be the parent before or after the
      *                        change, depending on the type of change
-     * @param changeFlags     a bitmask which indicates the type(s) of
-     *                        <code>HIERARCHY_CHANGED</code> events
-     *                        represented in this event object
+     * @param changeFlags     A bitmask which indicates the type(s) of
+     *                        the <code>HIERARCHY_CHANGED</code> events
+     *                        represented in this event object.
+     *                        For information on allowable values, see
+     *                        the class description for {@link HierarchyEvent}
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getSource()
+     * @see #getID()
+     * @see #getChanged()
+     * @see #getChangedParent()
+     * @see #getChangeFlags()
      */
     public HierarchyEvent(Component source, int id, Component changed,
                           Container changedParent, long changeFlags) {

src/share/classes/java/awt/event/InputEvent.java

@@ -208,17 +208,32 @@ public abstract class InputEvent extends ComponentEvent {
     /**
      * Constructs an InputEvent object with the specified source component,
      * modifiers, and type.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p> This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
      * @param source the object where the event originated
-     * @param id the event type
-     * @param when the time the event occurred
-     * @param modifiers represents the modifier keys and mouse buttons down
-     *                  while the event occurred
+     * @param id           the integer that identifies the event type.
+     *                     It is allowed to pass as parameter any value that
+     *                     allowed for some subclass of {@code InputEvent} class.
+     *                     Passing in the value different from those values result
+     *                     in unspecified behavior
+     * @param when         a long int that gives the time the event occurred.
+     *                     Passing negative or zero value
+     *                     is not recommended
+     * @param modifiers    the modifier keys down during event (e.g. shift, ctrl,
+     *                     alt, meta)
+     *                     Passing negative parameter is not recommended.
+     *                     Zero value means no modifiers.
+     *                     Either extended _DOWN_MASK or old _MASK modifiers
+     *                     should be used, but both models should not be mixed
+     *                     in one event. Use of the extended modifiers is
+     *                     preferred
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getSource()
+     * @see #getID()
+     * @see #getWhen()
+     * @see #getModifiers()
      */
     InputEvent(Component source, int id, long when, int modifiers) {
         super(source, id);
@@ -285,7 +300,8 @@ public abstract class InputEvent extends ComponentEvent {
     }
 
     /**
-     * Returns the timestamp of when this event occurred.
+     * Returns the difference in milliseconds between the timestamp of when this event occurred and
+     * midnight, January 1, 1970 UTC.
      */
     public long getWhen() {
         return when;
@@ -358,7 +374,12 @@ public abstract class InputEvent extends ComponentEvent {
      * Returns a String describing the extended modifier keys and
      * mouse buttons, such as "Shift", "Button1", or "Ctrl+Shift".
      * These strings can be localized by changing the
-     * awt.properties file.
+     * <code>awt.properties</code> file.
+     * <p>
+     * Note that passing negative parameter is incorrect,
+     * and will cause the returning an unspecified string.
+     * Zero parameter means that no modifiers were passed and will
+     * cause the returning an empty string.
      *
      * @param modifiers a modifier mask describing the extended
        *                modifier keys and mouse buttons for the event

src/share/classes/java/awt/event/InvocationEvent.java

 /*
- * Copyright 1998-2006 Sun Microsystems, Inc.  All Rights Reserved.
+ * Copyright 1998-2008 Sun Microsystems, Inc.  All Rights Reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -39,6 +39,10 @@ import java.awt.AWTEvent;
  * can use this fact to write replacement functions for <code>invokeLater
  * </code> and <code>invokeAndWait</code> without writing special-case code
  * in any <code>AWTEventListener</code> objects.
+ * <p>
+ * An unspecified behavior will be caused if the {@code id} parameter
+ * of any particular {@code InvocationEvent} instance is not
+ * in the range from {@code INVOCATION_FIRST} to {@code INVOCATION_LAST}.
  *
  * @author      Fred Ecks
  * @author      David Mendenhall
@@ -123,12 +127,13 @@ public class InvocationEvent extends AWTEvent implements ActiveEvent {
      * <p> This method throws an <code>IllegalArgumentException</code>
      * if <code>source</code> is <code>null</code>.
      *
-     * @param source    the <code>Object</code> that originated the event
-     * @param runnable  the <code>Runnable</code> whose <code>run</code>
+     * @param source    The <code>Object</code> that originated the event
+     * @param runnable  The <code>Runnable</code> whose <code>run</code>
      *                  method will be executed
      * @throws IllegalArgumentException if <code>source</code> is null
      *
-     * @see     #InvocationEvent(Object, Runnable, Object, boolean)
+     * @see #getSource()
+     * @see #InvocationEvent(Object, Runnable, Object, boolean)
      */
     public InvocationEvent(Object source, Runnable runnable) {
         this(source, runnable, null, false);
@@ -147,15 +152,15 @@ public class InvocationEvent extends AWTEvent implements ActiveEvent {
      * <p>This method throws an <code>IllegalArgumentException</code>
      * if <code>source</code> is <code>null</code>.
      *
-     * @param source            the <code>Object</code> that originated
+     * @param source            The <code>Object</code> that originated
      *                          the event
-     * @param runnable          the <code>Runnable</code> whose
+     * @param runnable          The <code>Runnable</code> whose
      *                          <code>run</code> method will be
      *                          executed
-     * @param notifier          the Object whose <code>notifyAll</code>
+     * @param notifier          The {@code Object} whose <code>notifyAll</code>
      *                          method will be called after
      *                          <code>Runnable.run</code> has returned
-     * @param catchThrowables   specifies whether <code>dispatch</code>
+     * @param catchThrowables   Specifies whether <code>dispatch</code>
      *                          should catch Throwable when executing
      *                          the <code>Runnable</code>'s <code>run</code>
      *                          method, or should instead propagate those
@@ -163,6 +168,7 @@ public class InvocationEvent extends AWTEvent implements ActiveEvent {
      *                          dispatch loop
      * @throws IllegalArgumentException if <code>source</code> is null
      *
+     * @see #getSource()
      * @see     #InvocationEvent(Object, int, Runnable, Object, boolean)
      */
     public InvocationEvent(Object source, Runnable runnable, Object notifier,
@@ -176,26 +182,29 @@ public class InvocationEvent extends AWTEvent implements ActiveEvent {
      * method when dispatched.  If notifier is non-<code>null</code>,
      * <code>notifyAll</code> will be called on it
      * immediately after <code>run</code> returns.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p>This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source            the <code>Object</code> that originated
+     * @param source            The <code>Object</code> that originated
      *                          the event
-     * @param id                the ID for the event
-     * @param runnable          the <code>Runnable</code> whose
+     * @param id     An integer indicating the type of event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link InvocationEvent}
+     * @param runnable          The <code>Runnable</code> whose
      *                          <code>run</code> method will be executed
-     * @param notifier          the <code>Object</code> whose <code>notifyAll</code>
+     * @param notifier          The <code>Object</code> whose <code>notifyAll</code>
      *                          method will be called after
      *                          <code>Runnable.run</code> has returned
-     * @param catchThrowables   specifies whether <code>dispatch</code>
+     * @param catchThrowables   Specifies whether <code>dispatch</code>
      *                          should catch Throwable when executing the
      *                          <code>Runnable</code>'s <code>run</code>
      *                          method, or should instead propagate those
      *                          Throwables to the EventDispatchThread's
      *                          dispatch loop
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getSource()
+     * @see #getID()
      */
     protected InvocationEvent(Object source, int id, Runnable runnable,
                               Object notifier, boolean catchThrowables) {

src/share/classes/java/awt/event/ItemEvent.java

@@ -41,6 +41,18 @@ import java.awt.ItemSelectable;
  * spared the details of processing individual mouse movements and mouse
  * clicks, and can instead process a "meaningful" (semantic) event like
  * "item selected" or "item deselected".
+ * <p>
+ * An unspecified behavior will be caused if the {@code id} parameter
+ * of any particular {@code ItemEvent} instance is not
+ * in the range from {@code ITEM_FIRST} to {@code ITEM_LAST}.
+ * <p>
+ * The {@code stateChange} of any {@code ItemEvent} instance takes one of the following
+ * values:
+ *                     <ul>
+ *                     <li> {@code ItemEvent.SELECTED}
+ *                     <li> {@code ItemEvent.DESELECTED}
+ *                     </ul>
+ * Assigning the value different from listed above will cause an unspecified behavior.
  *
  * @author Carl Quinn
  *
@@ -101,19 +113,24 @@ public class ItemEvent extends AWTEvent {
 
     /**
      * Constructs an <code>ItemEvent</code> object.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p> This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source the <code>ItemSelectable</code> object
+     * @param source The <code>ItemSelectable</code> object
      *               that originated the event
-     * @param id     an integer that identifies the event type
-     * @param item   an object -- the item affected by the event
-     * @param stateChange
-     *               an integer that indicates whether the item was
-     *               selected or deselected
+     * @param id           The integer that identifies the event type.
+     *                     For information on allowable values, see
+     *                     the class description for {@link ItemEvent}
+     * @param item   An object -- the item affected by the event
+     * @param stateChange  An integer that indicates whether the item was
+     *               selected or deselected.
+     *                     For information on allowable values, see
+     *                     the class description for {@link ItemEvent}
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getItemSelectable()
+     * @see #getID()
+     * @see #getStateChange()
      */
     public ItemEvent(ItemSelectable source, int id, Object item, int stateChange) {
         super(source, id);

src/share/classes/java/awt/event/KeyEvent.java

 /*
- * Copyright 1996-2007 Sun Microsystems, Inc.  All Rights Reserved.
+ * Copyright 1996-2008 Sun Microsystems, Inc.  All Rights Reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -128,6 +128,10 @@ import java.io.ObjectInputStream;
  * (VK_ENTER, VK_BACK_SPACE, and VK_TAB), do not rely on the values of the VK_
  * constants.  Sun reserves the right to change these values as needed
  * to accomodate a wider range of keyboards in the future.
+ * <p>
+ * An unspecified behavior will be caused if the {@code id} parameter
+ * of any particular {@code KeyEvent} instance is not
+ * in the range from {@code KEY_FIRST} to {@code KEY_LAST}.
  *
  * @author Carl Quinn
  * @author Amy Fowler
@@ -914,27 +918,32 @@ public class KeyEvent extends InputEvent {
 
     /**
      * Constructs a <code>KeyEvent</code> object.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p>This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source    the <code>Component</code> that originated the event
-     * @param id        an integer identifying the type of event
-     * @param when      a long integer that specifies the time the event
-     *                  occurred
-     * @param modifiers the modifier keys down during event (shift, ctrl,
-     *                  alt, meta)
-     *                  Either extended _DOWN_MASK or old _MASK modifiers
-     *                  should be used, but both models should not be mixed
-     *                  in one event. Use of the extended modifiers is
-     *                  preferred.
-     * @param keyCode   the integer code for an actual key, or VK_UNDEFINED
+     * @param source    The <code>Component</code> that originated the event
+     * @param id              An integer indicating the type of event.
+     *                  For information on allowable values, see
+     *                  the class description for {@link KeyEvent}
+     * @param when      A long integer that specifies the time the event
+     *                  occurred.
+     *                     Passing negative or zero value
+     *                     is not recommended
+     * @param modifiers The modifier keys down during event (shift, ctrl,
+     *                  alt, meta).
+     *                     Passing negative value
+     *                     is not recommended.
+     *                     Zero value means that no modifiers were passed.
+     *                  Use either an extended _DOWN_MASK or old _MASK modifiers,
+     *                  however do not mix models in the one event.
+     *                  The extended modifiers are preferred for using
+     * @param keyCode   The integer code for an actual key, or VK_UNDEFINED
      *                  (for a key-typed event)
-     * @param keyChar   the Unicode character generated by this event, or
+     * @param keyChar   The Unicode character generated by this event, or
      *                  CHAR_UNDEFINED (for key-pressed and key-released
      *                  events which do not map to a valid Unicode character)
-     * @param keyLocation  identifies the key location.  The only legal
+     * @param keyLocation  Identifies the key location.  The only legal
      *        values are <code>KEY_LOCATION_UNKNOWN</code>,
      *        <code>KEY_LOCATION_STANDARD</code>, <code>KEY_LOCATION_LEFT</code>,
      *        <code>KEY_LOCATION_RIGHT</code>, and <code>KEY_LOCATION_NUMPAD</code>.
@@ -948,6 +957,13 @@ public class KeyEvent extends InputEvent {
      *     or if <code>keyLocation</code> is not one of the legal
      *       values enumerated above.
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getSource()
+     * @see #getID()
+     * @see #getWhen()
+     * @see #getModifiers()
+     * @see #getKeyCode()
+     * @see #getKeyChar()
+     * @see #getKeyLocation()
      * @since 1.4
      */
     public KeyEvent(Component source, int id, long when, int modifiers,
@@ -982,24 +998,29 @@ public class KeyEvent extends InputEvent {
 
     /**
      * Constructs a <code>KeyEvent</code> object.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p> This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source    the <code>Component</code> that originated the event
-     * @param id        an integer identifying the type of event
-     * @param when      a long integer that specifies the time the event
-     *                  occurred
-     * @param modifiers the modifier keys down during event (shift, ctrl,
-     *                  alt, meta)
-     *                  Either extended _DOWN_MASK or old _MASK modifiers
-     *                  should be used, but both models should not be mixed
-     *                  in one event. Use of the extended modifiers is
-     *                  preferred.
-     * @param keyCode   the integer code for an actual key, or VK_UNDEFINED
+     * @param source    The <code>Component</code> that originated the event
+     * @param id              An integer indicating the type of event.
+     *                  For information on allowable values, see
+     *                  the class description for {@link KeyEvent}
+     * @param when      A long integer that specifies the time the event
+     *                  occurred.
+     *                     Passing negative or zero value
+     *                     is not recommended
+     * @param modifiers The modifier keys down during event (shift, ctrl,
+     *                  alt, meta).
+     *                     Passing negative value
+     *                     is not recommended.
+     *                     Zero value means that no modifiers were passed.
+     *                  Use either an extended _DOWN_MASK or old _MASK modifiers,
+     *                  however do not mix models in the one event.
+     *                  The extended modifiers are preferred for using
+     * @param keyCode   The integer code for an actual key, or VK_UNDEFINED
      *                  (for a key-typed event)
-     * @param keyChar   the Unicode character generated by this event, or
+     * @param keyChar   The Unicode character generated by this event, or
      *                  CHAR_UNDEFINED (for key-pressed and key-released
      *                  events which do not map to a valid Unicode character)
      * @throws IllegalArgumentException  if <code>id</code> is
@@ -1008,6 +1029,12 @@ public class KeyEvent extends InputEvent {
      *     <code>KEY_TYPED</code> and <code>keyCode</code> is not
      *     <code>VK_UNDEFINED</code>
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getSource()
+     * @see #getID()
+     * @see #getWhen()
+     * @see #getModifiers()
+     * @see #getKeyCode()
+     * @see #getKeyChar()
      */
     public KeyEvent(Component source, int id, long when, int modifiers,
                     int keyCode, char keyChar) {

src/share/classes/java/awt/event/MouseEvent.java

@@ -159,6 +159,11 @@ import java.awt.IllegalComponentStateException;
  * The reported coordinates for mouse drag events are clipped to fit within the
  * bounds of the virtual device associated with the <code>Component</code>.
  * </ul>
+ * <p>
+ * An unspecified behavior will be caused if the {@code id} parameter
+ * of any particular {@code MouseEvent} instance is not
+ * in the range from {@code MOUSE_FIRST} to {@code MOUSE_LAST}-1
+ * ({@code MOUSE_WHEEL} is not acceptable).
  *
  * @author Carl Quinn
  *
@@ -418,8 +423,7 @@ public class MouseEvent extends InputEvent {
      * specified source component,
      * type, modifiers, coordinates, and click count.
      * <p>
-     * Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior.  Creating an invalid event (such
+     * Creating an invalid event (such
      * as by using more than one of the old _MASKs, or modifier/button
      * values which don't match) results in unspecified behavior.
      * An invocation of the form
@@ -435,28 +439,44 @@ public class MouseEvent extends InputEvent {
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source       the <code>Component</code> that originated the event
-     * @param id           the integer that identifies the event
-     * @param when         a long int that gives the time the event occurred
-     * @param modifiers    the modifier keys down during event (e.g. shift, ctrl,
+     * @param source       The <code>Component</code> that originated the event
+     * @param id              An integer indicating the type of event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link MouseEvent}
+     * @param when         A long integer that gives the time the event occurred.
+     *                     Passing negative or zero value
+     *                     is not recommended
+     * @param modifiers    The modifier keys down during event (e.g. shift, ctrl,
      *                     alt, meta)
-     *                     Either extended _DOWN_MASK or old _MASK modifiers
-     *                     should be used, but both models should not be mixed
-     *                     in one event. Use of the extended modifiers is
-     *                     preferred.
-     * @param x            the horizontal x coordinate for the mouse location
-     * @param y            the vertical y coordinate for the mouse location
-     * @param clickCount   the number of mouse clicks associated with event
-     * @param popupTrigger a boolean, true if this event is a trigger for a
-     *                     popup menu
-     * @param button       which of the mouse buttons has changed state.
-     *                      <code>NOBUTTON</code>,
-     *                      <code>BUTTON1</code>,
-     *                      <code>BUTTON2</code> or
-     *                      <code>BUTTON3</code>.
+     *                     Passing negative parameter
+     *                     is not recommended.
+     *                     Zero value means that no modifiers were passed.
+     *                     Use either an extended _DOWN_MASK or old _MASK modifiers,
+     *                     however do not mix models in the one event.
+     *                     The extended modifiers are preferred for using
+     * @param x            The horizontal x coordinate for the mouse location.
+     *                       It is allowed to pass negative values
+     * @param y            The vertical y coordinate for the mouse location.
+     *                       It is allowed to pass negative values
+     * @param clickCount   The number of mouse clicks associated with event.
+     *                       Passing negative value
+     *                       is not recommended
+     * @param popupTrigger A boolean that equals {@code true} if this event
+     *                     is a trigger for a popup menu
+     * @param button       An integer that indicates, which of the mouse buttons has
+     *                     changed its state
      * @throws IllegalArgumentException if an invalid <code>button</code>
      *            value is passed in
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getSource()
+     * @see #getID()
+     * @see #getWhen()
+     * @see #getModifiers()
+     * @see #getX()
+     * @see #getY()
+     * @see #getClickCount()
+     * @see #isPopupTrigger()
+     * @see #getButton()
      * @since 1.4
      */
     public MouseEvent(Component source, int id, long when, int modifiers,
@@ -479,8 +499,6 @@ public class MouseEvent extends InputEvent {
      * Constructs a <code>MouseEvent</code> object with the
      * specified source component,
      * type, modifiers, coordinates, and click count.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior.
      * An invocation of the form
      * <tt>MouseEvent(source, id, when, modifiers, x, y, clickCount, popupTrigger)</tt>
      * behaves in exactly the same way as the invocation
@@ -493,21 +511,39 @@ public class MouseEvent extends InputEvent {
      * This method throws an <code>IllegalArgumentException</code>
      * if <code>source</code> is <code>null</code>.
      *
-     * @param source       the <code>Component</code> that originated the event
-     * @param id           the integer that identifies the event
-     * @param when         a long int that gives the time the event occurred
-     * @param modifiers    the modifier keys down during event (e.g. shift, ctrl,
+     * @param source       The <code>Component</code> that originated the event
+     * @param id              An integer indicating the type of event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link MouseEvent}
+     * @param when         A long integer that gives the time the event occurred.
+     *                     Passing negative or zero value
+     *                     is not recommended
+     * @param modifiers    The modifier keys down during event (e.g. shift, ctrl,
      *                     alt, meta)
-     *                     Either extended _DOWN_MASK or old _MASK modifiers
-     *                     should be used, but both models should not be mixed
-     *                     in one event. Use of the extended modifiers is
-     *                     preferred.
-     * @param x            the horizontal x coordinate for the mouse location
-     * @param y            the vertical y coordinate for the mouse location
-     * @param clickCount   the number of mouse clicks associated with event
-     * @param popupTrigger a boolean, true if this event is a trigger for a
-     *                     popup menu
+     *                     Passing negative parameter
+     *                     is not recommended.
+     *                     Zero value means that no modifiers were passed.
+     *                     Use either an extended _DOWN_MASK or old _MASK modifiers,
+     *                     however do not mix models in the one event.
+     *                     The extended modifiers are preferred for using
+     * @param x            The horizontal x coordinate for the mouse location.
+     *                       It is allowed to pass negative values
+     * @param y            The vertical y coordinate for the mouse location.
+     *                       It is allowed to pass negative values
+     * @param clickCount   The number of mouse clicks associated with event.
+     *                       Passing negative value
+     *                       is not recommended
+     * @param popupTrigger A boolean that equals {@code true} if this event
+     *                     is a trigger for a popup menu
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getSource()
+     * @see #getID()
+     * @see #getWhen()
+     * @see #getModifiers()
+     * @see #getX()
+     * @see #getY()
+     * @see #getClickCount()
+     * @see #isPopupTrigger()
      */
      public MouseEvent(Component source, int id, long when, int modifiers,
                       int x, int y, int clickCount, boolean popupTrigger) {
@@ -520,8 +556,7 @@ public class MouseEvent extends InputEvent {
      * specified source component,
      * type, modifiers, coordinates, absolute coordinates, and click count.
      * <p>
-     * Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior.  Creating an invalid event (such
+     * Creating an invalid event (such
      * as by using more than one of the old _MASKs, or modifier/button
      * values which don't match) results in unspecified behavior.
      * Even if inconsistent values for relative and absolute coordinates are
@@ -531,30 +566,50 @@ public class MouseEvent extends InputEvent {
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source       the <code>Component</code> that originated the event
-     * @param id           the integer that identifies the event
-     * @param when         a long int that gives the time the event occurred
-     * @param modifiers    the modifier keys down during event (e.g. shift, ctrl,
+     * @param source       The <code>Component</code> that originated the event
+     * @param id              An integer indicating the type of event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link MouseEvent}
+     * @param when         A long integer that gives the time the event occurred.
+     *                     Passing negative or zero value
+     *                     is not recommended
+     * @param modifiers    The modifier keys down during event (e.g. shift, ctrl,
      *                     alt, meta)
-     *                     Either extended _DOWN_MASK or old _MASK modifiers
-     *                     should be used, but both models should not be mixed
-     *                     in one event. Use of the extended modifiers is
-     *                     preferred.
-     * @param x            the horizontal x coordinate for the mouse location
-     * @param y            the vertical y coordinate for the mouse location
-     * @param xAbs         the absolute horizontal x coordinate for the mouse location
-     * @param yAbs         the absolute vertical y coordinate for the mouse location
-     * @param clickCount   the number of mouse clicks associated with event
-     * @param popupTrigger a boolean, true if this event is a trigger for a
-     *                     popup menu
-     * @param button       which of the mouse buttons has changed state.
-     *                      <code>NOBUTTON</code>,
-     *                      <code>BUTTON1</code>,
-     *                      <code>BUTTON2</code> or
-     *                      <code>BUTTON3</code>.
+     *                     Passing negative parameter
+     *                     is not recommended.
+     *                     Zero value means that no modifiers were passed.
+     *                     Use either an extended _DOWN_MASK or old _MASK modifiers,
+     *                     however do not mix models in the one event.
+     *                     The extended modifiers are preferred for using
+     * @param x            The horizontal x coordinate for the mouse location.
+     *                       It is allowed to pass negative values
+     * @param y            The vertical y coordinate for the mouse location.
+     *                       It is allowed to pass negative values
+     * @param xAbs           The absolute horizontal x coordinate for the mouse location
+     *                       It is allowed to pass negative values
+     * @param yAbs           The absolute vertical y coordinate for the mouse location
+     *                       It is allowed to pass negative values
+     * @param clickCount   The number of mouse clicks associated with event.
+     *                       Passing negative value
+     *                       is not recommended
+     * @param popupTrigger A boolean that equals {@code true} if this event
+     *                     is a trigger for a popup menu
+     * @param button       An integer that indicates, which of the mouse buttons has
+     *                     changed its state
      * @throws IllegalArgumentException if an invalid <code>button</code>
      *            value is passed in
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getSource()
+     * @see #getID()
+     * @see #getWhen()
+     * @see #getModifiers()
+     * @see #getX()
+     * @see #getY()
+     * @see #getXOnScreen()
+     * @see #getYOnScreen()
+     * @see #getClickCount()
+     * @see #isPopupTrigger()
+     * @see #getButton()
      * @since 1.6
      */
     public MouseEvent(Component source, int id, long when, int modifiers,
@@ -675,21 +730,26 @@ public class MouseEvent extends InputEvent {
     }
 
     /**
-     * Returns a <code>String</code> describing the modifier keys and
+     * Returns a <code>String</code> instance describing the modifier keys and
      * mouse buttons that were down during the event, such as "Shift",
      * or "Ctrl+Shift". These strings can be localized by changing
      * the <code>awt.properties</code> file.
      * <p>
-     * Note that <code>InputEvent.ALT_MASK</code> and
-     * <code>InputEvent.BUTTON2_MASK</code> have the same value,
-     * so the string "Alt" is returned for both modifiers.  Likewise,
-     * <code>InputEvent.META_MASK</code> and
-     * <code>InputEvent.BUTTON3_MASK</code> have the same value,
-     * so the string "Meta" is returned for both modifiers.
+     * Note that the <code>InputEvent.ALT_MASK</code> and
+     * <code>InputEvent.BUTTON2_MASK</code> have equal values,
+     * so the "Alt" string is returned for both modifiers.  Likewise,
+     * the <code>InputEvent.META_MASK</code> and
+     * <code>InputEvent.BUTTON3_MASK</code> have equal values,
+     * so the "Meta" string is returned for both modifiers.
+     * <p>
+     * Note that passing negative parameter is incorrect,
+     * and will cause the returning an unspecified string.
+     * Zero parameter means that no modifiers were passed and will
+     * cause the returning an empty string.
      *
-     * @param modifiers a modifier mask describing the modifier keys and
+     * @param modifiers A modifier mask describing the modifier keys and
      *                  mouse buttons that were down during the event
-     * @return string   a text description of the combination of modifier
+     * @return string   string text description of the combination of modifier
      *                  keys and mouse buttons that were down during the event
      * @see InputEvent#getModifiersExText(int)
      * @since 1.4

src/share/classes/java/awt/event/MouseWheelEvent.java

 /*
- * Copyright 2000-2007 Sun Microsystems, Inc.  All Rights Reserved.
+ * Copyright 2000-2008 Sun Microsystems, Inc.  All Rights Reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it

src/share/classes/java/awt/event/PaintEvent.java

@@ -36,6 +36,10 @@ import java.awt.Rectangle;
  * designed to be used with the Event Listener model; programs
  * should continue to override paint/update methods in order
  * render themselves properly.
+ * <p>
+ * An unspecified behavior will be caused if the {@code id} parameter
+ * of any particular {@code PaintEvent} instance is not
+ * in the range from {@code PAINT_FIRST} to {@code PAINT_LAST}.
  *
  * @author Amy Fowler
  * @since 1.1
@@ -82,15 +86,19 @@ public class PaintEvent extends ComponentEvent {
     /**
      * Constructs a <code>PaintEvent</code> object with the specified
      * source component and type.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p> This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source     the object where the event originated
-     * @param id         the event type
-     * @param updateRect the rectangle area which needs to be repainted
+     * @param source     The object where the event originated
+     * @param id           The integer that identifies the event type.
+     *                     For information on allowable values, see
+     *                     the class description for {@link PaintEvent}
+     * @param updateRect The rectangle area which needs to be repainted
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getSource()
+     * @see #getID()
+     * @see #getUpdateRect()
      */
     public PaintEvent(Component source, int id, Rectangle updateRect) {
         super(source, id);

src/share/classes/java/awt/event/TextEvent.java

@@ -38,6 +38,10 @@ import java.awt.AWTEvent;
  * this <code>TextEvent</code> when the event occurs. The listener is
  * spared the details of processing individual mouse movements and key strokes
  * Instead, it can process a "meaningful" (semantic) event like "text changed".
+ * <p>
+ * An unspecified behavior will be caused if the {@code id} parameter
+ * of any particular {@code TextEvent} instance is not
+ * in the range from {@code TEXT_FIRST} to {@code TEXT_LAST}.
  *
  * @author Georges Saab
  *
@@ -71,15 +75,18 @@ public class TextEvent extends AWTEvent {
 
     /**
      * Constructs a <code>TextEvent</code> object.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p> This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source the (<code>TextComponent</code>) object that
+     * @param source The (<code>TextComponent</code>) object that
      *               originated the event
-     * @param id     an integer that identifies the event type
+     * @param id     An integer that identifies the event type.
+     *                     For information on allowable values, see
+     *                     the class description for {@link TextEvent}
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getSource()
+     * @see #getID()
      */
     public TextEvent(Object source, int id) {
         super(source, id);

src/share/classes/java/awt/event/WindowEvent.java

@@ -41,6 +41,10 @@ import sun.awt.SunToolkit;
  * (<code>WindowAdapter</code> objects implement the
  * <code>WindowListener</code> interface.) Each such listener object
  * gets this <code>WindowEvent</code> when the event occurs.
+ * <p>
+ * An unspecified behavior will be caused if the {@code id} parameter
+ * of any particular {@code WindowEvent} instance is not
+ * in the range from {@code WINDOW_FIRST} to {@code WINDOW_LAST}.
  *
  * @author Carl Quinn
  * @author Amy Fowler
@@ -170,20 +174,27 @@ public class WindowEvent extends ComponentEvent {
 
     /**
      * Constructs a <code>WindowEvent</code> object.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p>This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source    the <code>Window</code> object
+     * @param source    The <code>Window</code> object
      *                    that originated the event
-     * @param id        an integer indicating the type of event.
-     * @param opposite  the other window involved in the focus or activation
+     * @param id        An integer indicating the type of event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link WindowEvent}
+     * @param opposite  The other window involved in the focus or activation
      *                      change, or <code>null</code>
-     * @param oldState  previous state of the window for window state
-     *                      change event
-     * @param newState  new state of the window for window state change event
+     * @param oldState  Previous state of the window for window state change event.
+     *                  See {@code #getOldState()} for allowable values
+     * @param newState  New state of the window for window state change event.
+     *                  See {@code #getNewState()} for allowable values
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getWindow()
+     * @see #getID()
+     * @see #getOppositeWindow()
+     * @see #getOldState()
+     * @see #getNewState()
      * @since 1.4
      */
     public WindowEvent(Window source, int id, Window opposite,
@@ -209,24 +220,28 @@ public class WindowEvent extends ComponentEvent {
      * If this focus change occurs with a native application, with a
      * Java application in a different VM, or with no other
      * <code>Window</code>, then the opposite Window is <code>null</code>.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p>This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source     the <code>Window</code> object that
+     * @param source     The <code>Window</code> object that
      *                   originated the event
-     * @param id         <code>WINDOW_ACTIVATED</code>,
-     *                   <code>WINDOW_DEACTIVATED</code>,
-     *                   <code>WINDOW_GAINED_FOCUS</code>,
-     *                   or <code>WINDOW_LOST_FOCUS</code>. It is
-     *                   expected that this constructor will not be used for
-     *                   other <code>WindowEvent</code> types because the
-     *                   opposite <code>Window</code> of such events
-     *                   will always be <code>null</code>
-     * @param opposite   the other <code>Window</code> involved in the
+     * @param id        An integer indicating the type of event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link WindowEvent}.
+     *                  It is expected that this constructor will not
+     *                  be used for other then
+     *                  {@code WINDOW_ACTIVATED},{@code WINDOW_DEACTIVATED},
+     *                  {@code WINDOW_GAINED_FOCUS}, or {@code WINDOW_LOST_FOCUS}.
+     *                  {@code WindowEvent} types,
+     *                  because the opposite <code>Window</code> of other event types
+     *                  will always be {@code null}.
+     * @param opposite   The other <code>Window</code> involved in the
      *                   focus or activation change, or <code>null</code>
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getWindow()
+     * @see #getID()
+     * @see #getOppositeWindow()
      * @since 1.4
      */
     public WindowEvent(Window source, int id, Window opposite) {
@@ -236,21 +251,30 @@ public class WindowEvent extends ComponentEvent {
     /**
      * Constructs a <code>WindowEvent</code> object with the specified
      * previous and new window states.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p>This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source    the <code>Window</code> object
+     * @param source    The <code>Window</code> object
      *                  that originated the event
-     * @param id        <code>WINDOW_STATE_CHANGED</code> event type.
+     * @param id        An integer indicating the type of event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link WindowEvent}.
      *                  It is expected that this constructor will not
-     *                  be used for other <code>WindowEvent</code>
+     *                  be used for other then
+     *                  {@code WINDOW_STATE_CHANGED}
+     *                  {@code WindowEvent}
      *                  types, because the previous and new window
      *                  states are meaningless for other event types.
-     * @param oldState  an integer representing the previous window state
-     * @param newState  an integer representing the new window state
+     * @param oldState  An integer representing the previous window state.
+     *                  See {@code #getOldState()} for allowable values
+     * @param newState  An integer representing the new window state.
+     *                  See {@code #getNewState()} for allowable values
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getWindow()
+     * @see #getID()
+     * @see #getOldState()
+     * @see #getNewState()
      * @since 1.4
      */
     public WindowEvent(Window source, int id, int oldState, int newState) {
@@ -259,14 +283,17 @@ public class WindowEvent extends ComponentEvent {
 
     /**
      * Constructs a <code>WindowEvent</code> object.
-     * <p>Note that passing in an invalid <code>id</code> results in
-     * unspecified behavior. This method throws an
+     * <p>This method throws an
      * <code>IllegalArgumentException</code> if <code>source</code>
      * is <code>null</code>.
      *
-     * @param source the <code>Window</code> object that originated the event
-     * @param id     an integer indicating the type of event
+     * @param source The <code>Window</code> object that originated the event
+     * @param id     An integer indicating the type of event.
+     *                     For information on allowable values, see
+     *                     the class description for {@link WindowEvent}.
      * @throws IllegalArgumentException if <code>source</code> is null
+     * @see #getWindow()
+     * @see #getID()
      */
     public WindowEvent(Window source, int id) {
         this(source, id, null, 0, 0);