changeset 883:63d087cacbf9

6792515: Specify awt peer's API Summary: Document AWT peer API. Reviewed-by: art, dav
author rkennke
date Tue, 13 Jan 2009 20:04:05 +0100
parents d5bf2dd61ed5
children 127e3269ee1f
files src/share/classes/java/awt/peer/ButtonPeer.java src/share/classes/java/awt/peer/CanvasPeer.java src/share/classes/java/awt/peer/CheckboxMenuItemPeer.java src/share/classes/java/awt/peer/CheckboxPeer.java src/share/classes/java/awt/peer/ChoicePeer.java src/share/classes/java/awt/peer/ComponentPeer.java src/share/classes/java/awt/peer/ContainerPeer.java src/share/classes/java/awt/peer/DesktopPeer.java src/share/classes/java/awt/peer/DialogPeer.java src/share/classes/java/awt/peer/FileDialogPeer.java src/share/classes/java/awt/peer/FontPeer.java src/share/classes/java/awt/peer/FramePeer.java src/share/classes/java/awt/peer/KeyboardFocusManagerPeer.java src/share/classes/java/awt/peer/LabelPeer.java src/share/classes/java/awt/peer/ListPeer.java src/share/classes/java/awt/peer/MenuBarPeer.java src/share/classes/java/awt/peer/MenuComponentPeer.java src/share/classes/java/awt/peer/MenuItemPeer.java src/share/classes/java/awt/peer/MenuPeer.java src/share/classes/java/awt/peer/MouseInfoPeer.java src/share/classes/java/awt/peer/PanelPeer.java src/share/classes/java/awt/peer/PopupMenuPeer.java src/share/classes/java/awt/peer/RobotPeer.java src/share/classes/java/awt/peer/ScrollPanePeer.java src/share/classes/java/awt/peer/ScrollbarPeer.java src/share/classes/java/awt/peer/SystemTrayPeer.java src/share/classes/java/awt/peer/TextAreaPeer.java src/share/classes/java/awt/peer/TextComponentPeer.java src/share/classes/java/awt/peer/TextFieldPeer.java src/share/classes/java/awt/peer/TrayIconPeer.java src/share/classes/java/awt/peer/WindowPeer.java
diffstat 31 files changed, 1446 insertions(+), 67 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/java/awt/peer/ButtonPeer.java	Fri Dec 19 16:04:04 2008 +0300
+++ b/src/share/classes/java/awt/peer/ButtonPeer.java	Tue Jan 13 20:04:05 2009 +0100
@@ -25,7 +25,11 @@
 
 package java.awt.peer;
 
+import java.awt.Button;
+
 /**
+ * The peer interface for {@link Button}.
+ *
  * The peer interfaces are intended only for use in porting
  * the AWT. They are not intended for use by application
  * developers, and developers should not implement peers
@@ -33,5 +37,14 @@
  * instances.
  */
 public interface ButtonPeer extends ComponentPeer {
+
+    /**
+     * Sets the label that is displayed on the button. Can be {@code null}
+     * when the button should not display a label.
+     *
+     * @param label the label string to set
+     *
+     * @see Button#setLabel
+     */
     void setLabel(String label);
 }
--- a/src/share/classes/java/awt/peer/CanvasPeer.java	Fri Dec 19 16:04:04 2008 +0300
+++ b/src/share/classes/java/awt/peer/CanvasPeer.java	Tue Jan 13 20:04:05 2009 +0100
@@ -24,7 +24,11 @@
  */
 package java.awt.peer;
 
+import java.awt.Canvas;
+
 /**
+ * The peer interface for {@link Canvas}.
+ *
  * The peer interfaces are intended only for use in porting
  * the AWT. They are not intended for use by application
  * developers, and developers should not implement peers
--- a/src/share/classes/java/awt/peer/CheckboxMenuItemPeer.java	Fri Dec 19 16:04:04 2008 +0300
+++ b/src/share/classes/java/awt/peer/CheckboxMenuItemPeer.java	Tue Jan 13 20:04:05 2009 +0100
@@ -24,7 +24,11 @@
  */
 package java.awt.peer;
 
+import java.awt.CheckboxMenuItem;
+
 /**
+ * The peer interface for {@link CheckboxMenuItem}.
+ *
  * The peer interfaces are intended only for use in porting
  * the AWT. They are not intended for use by application
  * developers, and developers should not implement peers
@@ -32,5 +36,14 @@
  * instances.
  */
 public interface CheckboxMenuItemPeer extends MenuItemPeer {
+
+    /**
+     * Sets the state of the checkbox to be checked ({@code true}) or
+     * unchecked ({@code false}).
+     *
+     * @param t the state to set on the checkbox
+     *
+     * @see CheckboxMenuItemPeer#setState(boolean)
+     */
     void setState(boolean t);
 }
--- a/src/share/classes/java/awt/peer/CheckboxPeer.java	Fri Dec 19 16:04:04 2008 +0300
+++ b/src/share/classes/java/awt/peer/CheckboxPeer.java	Tue Jan 13 20:04:05 2009 +0100
@@ -27,6 +27,8 @@
 import java.awt.*;
 
 /**
+ * The peer interface for {@link Checkbox}.
+ *
  * The peer interfaces are intended only for use in porting
  * the AWT. They are not intended for use by application
  * developers, and developers should not implement peers
@@ -34,7 +36,36 @@
  * instances.
  */
 public interface CheckboxPeer extends ComponentPeer {
+
+    /**
+     * Sets the state of the checkbox to be checked ({@code true}) or
+     * unchecked ({@code false}).
+     *
+     * @param t the state to set on the checkbox
+     *
+     * @see Checkbox#setState(boolean)
+     */
     void setState(boolean state);
+
+    /**
+     * Sets the checkbox group for this checkbox. Checkboxes in one checkbox
+     * group can only be selected exclusively (like radio buttons). A value
+     * of {@code null} removes this checkbox from any checkbox group.
+     *
+     * @param g the checkbox group to set, or {@code null} when this
+     *          checkbox should not be placed in any group
+     *
+     * @see Checkbox#setCheckboxGroup(CheckboxGroup)
+     */
     void setCheckboxGroup(CheckboxGroup g);
+
+    /**
+     * Sets the label that should be displayed on the ckeckbox. A value of
+     * {@code null} means that no label should be displayed.
+     *
+     * @param label the label to be displayed on the checkbox, or
+     *              {@code null} when no label should be displayed.
+     */
     void setLabel(String label);
+
 }
--- a/src/share/classes/java/awt/peer/ChoicePeer.java	Fri Dec 19 16:04:04 2008 +0300
+++ b/src/share/classes/java/awt/peer/ChoicePeer.java	Tue Jan 13 20:04:05 2009 +0100
@@ -24,7 +24,11 @@
  */
 package java.awt.peer;
 
+import java.awt.Choice;
+
 /**
+ * The peer interface for {@link Choice}.
+ *
  * The peer interfaces are intended only for use in porting
  * the AWT. They are not intended for use by application
  * developers, and developers should not implement peers
@@ -32,9 +36,41 @@
  * instances.
  */
 public interface ChoicePeer extends ComponentPeer {
+
+    /**
+     * Adds an item with the string {@code item} to the combo box list
+     * at index {@code index}.
+     *
+     * @param item the label to be added to the list
+     * @param index the index where to add the item
+     *
+     * @see Choice#add(String)
+     */
     void add(String item, int index);
+
+    /**
+     * Removes the item at index {@code index} from the combo box list.
+     *
+     * @param index the index where to remove the item
+     *
+     * @see Choice#remove(int)
+     */
     void remove(int index);
+
+    /**
+     * Removes all items from the combo box list.
+     *
+     * @see Choice#removeAll()
+     */
     void removeAll();
+
+    /**
+     * Selects the item at index {@code index}.
+     *
+     * @param index the index which should be selected
+     *
+     * @see Choice#select(int)
+     */
     void select(int index);
 
 }
--- a/src/share/classes/java/awt/peer/ComponentPeer.java	Fri Dec 19 16:04:04 2008 +0300
+++ b/src/share/classes/java/awt/peer/ComponentPeer.java	Tue Jan 13 20:04:05 2009 +0100
@@ -37,6 +37,12 @@
 
 
 /**
+ * The peer interface for {@link Component}. This is the top level peer
+ * interface for widgets and defines the bulk of methods for AWT component
+ * peers. Most component peers have to implement this interface (via one
+ * of the subinterfaces), except menu components, which implement
+ * {@link MenuComponentPeer}.
+ *
  * The peer interfaces are intended only for use in porting
  * the AWT. They are not intended for use by application
  * developers, and developers should not implement peers
@@ -44,62 +50,474 @@
  * instances.
  */
 public interface ComponentPeer {
-    public static final int SET_LOCATION = 1,
-        SET_SIZE = 2,
-        SET_BOUNDS = 3,
-        SET_CLIENT_SIZE = 4,
-        RESET_OPERATION = 5,
-        NO_EMBEDDED_CHECK = (1 << 14),
-        DEFAULT_OPERATION = SET_BOUNDS;
+
+    /**
+     * Operation for {@link #setBounds(int, int, int, int, int)}, indicating
+     * a change in the component location only.
+     *
+     * @see #setBounds(int, int, int, int, int)
+     */
+    public static final int SET_LOCATION = 1;
+
+    /**
+     * Operation for {@link #setBounds(int, int, int, int, int)}, indicating
+     * a change in the component size only.
+     *
+     * @see #setBounds(int, int, int, int, int)
+     */
+    public static final int SET_SIZE = 2;
+
+    /**
+     * Operation for {@link #setBounds(int, int, int, int, int)}, indicating
+     * a change in the component size and location.
+     *
+     * @see #setBounds(int, int, int, int, int)
+     */
+    public static final int SET_BOUNDS = 3;
+
+    /**
+     * Operation for {@link #setBounds(int, int, int, int, int)}, indicating
+     * a change in the component client size. This is used for setting
+     * the 'inside' size of windows, without the border insets.
+     *
+     * @see #setBounds(int, int, int, int, int)
+     */
+    public static final int SET_CLIENT_SIZE = 4;
+
+    /**
+     * Resets the setBounds() operation to DEFAULT_OPERATION. This is not
+     * passed into {@link #setBounds(int, int, int, int, int)}.
+     *
+     * TODO: This is only used internally and should probably be moved outside
+     *       the peer interface.
+     *
+     * @see Component#setBoundsOp
+     */
+    public static final int RESET_OPERATION = 5;
+
+    /**
+     * A flag that is used to suppress checks for embedded frames.
+     *
+     * TODO: This is only used internally and should probably be moved outside
+     *       the peer interface.
+     */
+    public static final int NO_EMBEDDED_CHECK = (1 << 14);
+
+    /**
+     * The default operation, which is to set size and location.
+     *
+     * TODO: This is only used internally and should probably be moved outside
+     *       the peer interface.
+     *
+     * @see Component#setBoundsOp
+     */
+    public static final int DEFAULT_OPERATION = SET_BOUNDS;
+
+    /**
+     * Determines if a component has been obscured, i.e. by an overlapping
+     * window or similar. This is used by JViewport for optimizing performance.
+     * This doesn't have to be implemented, when
+     * {@link #canDetermineObscurity()} returns {@code false}.
+     *
+     * @return {@code true} when the component has been obscured,
+     *         {@code false} otherwise
+     *
+     * @see #canDetermineObscurity()
+     * @see javax.swing.JViewport#needsRepaintAfterBlit
+     */
     boolean isObscured();
+
+    /**
+     * Returns {@code true} when the peer can determine if a component
+     * has been obscured, {@code false} false otherwise.
+     *
+     * @return {@code true} when the peer can determine if a component
+     *         has been obscured, {@code false} false otherwise
+     *
+     * @see #isObscured()
+     * @see javax.swing.JViewport#needsRepaintAfterBlit
+     */
     boolean canDetermineObscurity();
-    void                setVisible(boolean b);
-    void                setEnabled(boolean b);
-    void                paint(Graphics g);
-    void                print(Graphics g);
-    void                setBounds(int x, int y, int width, int height, int op);
-    void                handleEvent(AWTEvent e);
-    void                coalescePaintEvent(PaintEvent e);
-    Point               getLocationOnScreen();
-    Dimension           getPreferredSize();
-    Dimension           getMinimumSize();
-    ColorModel          getColorModel();
-    Toolkit             getToolkit();
-    Graphics            getGraphics();
-    FontMetrics         getFontMetrics(Font font);
-    void                dispose();
-    void                setForeground(Color c);
-    void                setBackground(Color c);
-    void                setFont(Font f);
-    void                updateCursorImmediately();
-    boolean             requestFocus(Component lightweightChild,
-                                     boolean temporary,
-                                     boolean focusedWindowChangeAllowed,
-                                     long time, CausedFocusEvent.Cause cause);
-    boolean             isFocusable();
 
-    Image               createImage(ImageProducer producer);
-    Image               createImage(int width, int height);
-    VolatileImage       createVolatileImage(int width, int height);
-    boolean             prepareImage(Image img, int w, int h, ImageObserver o);
-    int                 checkImage(Image img, int w, int h, ImageObserver o);
+    /**
+     * Makes a component visible or invisible.
+     *
+     * @param v {@code true} to make a component visible,
+     *          {@code false} to make it invisible
+     *
+     * @see Component#setVisible(boolean)
+     */
+    void setVisible(boolean v);
+
+    /**
+     * Enables or disables a component. Disabled components are usually grayed
+     * out and cannot be activated.
+     *
+     * @param e {@code true} to enable the component, {@code false}
+     *          to disable it
+     *
+     * @see Component#setEnabled(boolean)
+     */
+    void setEnabled(boolean e);
+
+    /**
+     * Paints the component to the specified graphics context. This is called
+     * by {@link Component#paintAll(Graphics)} to paint the component.
+     *
+     * @param g the graphics context to paint to
+     *
+     * @see Component#paintAll(Graphics)
+     */
+    void paint(Graphics g);
+
+    /**
+     * Prints the component to the specified graphics context. This is called
+     * by {@link Component#printAll(Graphics)} to print the component.
+     *
+     * @param g the graphics context to print to
+     *
+     * @see Component#printAll(Graphics)
+     */
+    void print(Graphics g);
+
+    /**
+     * Sets the location or size or both of the component. The location is
+     * specified relative to the component's parent. The {@code op}
+     * parameter specifies which properties change. If it is
+     * {@link #SET_LOCATION}, then only the location changes (and the size
+     * parameters can be ignored). If {@code op} is {@link #SET_SIZE},
+     * then only the size changes (and the location can be ignored). If
+     * {@code op} is {@link #SET_BOUNDS}, then both change. There is a
+     * special value {@link #SET_CLIENT_SIZE}, which is used only for
+     * window-like components to set the size of the client (i.e. the 'inner'
+     * size, without the insets of the window borders).
+     *
+     * @param x the X location of the component
+     * @param y the Y location of the component
+     * @param width the width of the component
+     * @param height the height of the component
+     * @param op the operation flag
+     *
+     * @see #SET_BOUNDS
+     * @see #SET_LOCATION
+     * @see #SET_SIZE
+     * @see #SET_CLIENT_SIZE
+     */
+    void setBounds(int x, int y, int width, int height, int op);
+
+    /**
+     * Called to let the component peer handle events.
+     *
+     * @param e the AWT event to handle
+     *
+     * @see Component#dispatchEvent(AWTEvent)
+     */
+    void handleEvent(AWTEvent e);
+
+    /**
+     * Called to coalesce paint events.
+     *
+     * @param e the paint event to consider to coalesce
+     *
+     * @see EventQueue#coalescePaintEvent
+     */
+    void coalescePaintEvent(PaintEvent e);
+
+    /**
+     * Determines the location of the component on the screen.
+     *
+     * @return the location of the component on the screen
+     *
+     * @see Component#getLocationOnScreen()
+     */
+    Point getLocationOnScreen();
+
+    /**
+     * Determines the preferred size of the component.
+     *
+     * @return the preferred size of the component
+     *
+     * @see Component#getPreferredSize()
+     */
+    Dimension getPreferredSize();
+
+    /**
+     * Determines the minimum size of the component.
+     *
+     * @return the minimum size of the component
+     *
+     * @see Component#getMinimumSize()
+     */
+    Dimension getMinimumSize();
+
+    /**
+     * Returns the color model used by the component.
+     *
+     * @return the color model used by the component
+     *
+     * @see Component#getColorModel()
+     */
+    ColorModel getColorModel();
+
+    /**
+     * Returns the toolkit that is responsible for the component.
+     *
+     * @return the toolkit that is responsible for the component
+     *
+     * @see Component#getToolkit()
+     */
+    Toolkit getToolkit();
+
+    /**
+     * Returns a graphics object to paint on the component.
+     *
+     * @return a graphics object to paint on the component
+     *
+     * @see Component#getGraphics()
+     */
+    // TODO: Maybe change this to force Graphics2D, since many things will
+    // break with plain Graphics nowadays.
+    Graphics getGraphics();
+
+    /**
+     * Returns a font metrics object to determine the metrics properties of
+     * the specified font.
+     *
+     * @param font the font to determine the metrics for
+     *
+     * @return a font metrics object to determine the metrics properties of
+     *         the specified font
+     *
+     * @see Component#getFontMetrics(Font)
+     */
+    FontMetrics getFontMetrics(Font font);
+
+    /**
+     * Disposes all resources held by the component peer. This is called
+     * when the component has been disconnected from the component hierarchy
+     * and is about to be garbage collected.
+     *
+     * @see Component#removeNotify()
+     */
+    void dispose();
+
+    /**
+     * Sets the foreground color of this component.
+     *
+     * @param c the foreground color to set
+     *
+     * @see Component#setForeground(Color)
+     */
+    void setForeground(Color c);
+
+    /**
+     * Sets the background color of this component.
+     *
+     * @param c the background color to set
+     *
+     * @see Component#setBackground(Color)
+     */
+    void setBackground(Color c);
+
+    /**
+     * Sets the font of this component.
+     *
+     * @param f the font of this component
+     *
+     * @see Component#setFont(Font)
+     */
+    void setFont(Font f);
+
+    /**
+     * Updates the cursor of the component.
+     *
+     * @see Component#updateCursorImmediately
+     */
+    void updateCursorImmediately();
+
+    /**
+     * Requests focus on this component.
+     *
+     * @param lightweightChild the actual lightweight child that requests the
+     *        focus
+     * @param temporary {@code true} if the focus change is temporary,
+     *        {@code false} otherwise
+     * @param focusedWindowChangeAllowed {@code true} if changing the
+     *        focus of the containing window is allowed or not
+     * @param time the time of the focus change request
+     * @param cause the cause of the focus change request
+     *
+     * @return {@code true} if the focus change is guaranteed to be
+     *         granted, {@code false} otherwise
+     */
+    boolean requestFocus(Component lightweightChild, boolean temporary,
+                         boolean focusedWindowChangeAllowed, long time,
+                         CausedFocusEvent.Cause cause);
+
+    /**
+     * Returns {@code true} when the component takes part in the focus
+     * traversal, {@code false} otherwise.
+     *
+     * @return {@code true} when the component takes part in the focus
+     *         traversal, {@code false} otherwise
+     */
+    boolean isFocusable();
+
+    /**
+     * Creates an image using the specified image producer.
+     *
+     * @param producer the image producer from which the image pixels will be
+     *        produced
+     *
+     * @return the created image
+     *
+     * @see Component#createImage(ImageProducer)
+     */
+    Image createImage(ImageProducer producer);
+
+    /**
+     * Creates an empty image with the specified width and height. This is
+     * generally used as a non-accelerated backbuffer for drawing onto the
+     * component (e.g. by Swing).
+     *
+     * @param width the width of the image
+     * @param height the height of the image
+     *
+     * @return the created image
+     *
+     * @see Component#createImage(int, int)
+     */
+    // TODO: Maybe make that return a BufferedImage, because some stuff will
+    // break if a different kind of image is returned.
+    Image createImage(int width, int height);
+
+    /**
+     * Creates an empty volatile image with the specified width and height.
+     * This is generally used as an accelerated backbuffer for drawing onto
+     * the component (e.g. by Swing).
+     *
+     * @param width the width of the image
+     * @param height the height of the image
+     *
+     * @return the created volatile image
+     *
+     * @see Component#createVolatileImage(int, int)
+     */
+    // TODO: Include capabilities here and fix Component#createVolatileImage
+    VolatileImage createVolatileImage(int width, int height);
+
+    /**
+     * Prepare the specified image for rendering on this component. This should
+     * start loading the image (if not already loaded) and create an
+     * appropriate screen representation.
+     *
+     * @param img the image to prepare
+     * @param w the width of the screen representation
+     * @param h the height of the screen representation
+     * @param o an image observer to observe the progress
+     *
+     * @return {@code true} if the image is already fully prepared,
+     *         {@code false} otherwise
+     *
+     * @see Component#prepareImage(Image, int, int, ImageObserver)
+     */
+    boolean prepareImage(Image img, int w, int h, ImageObserver o);
+
+    /**
+     * Determines the status of the construction of the screen representaion
+     * of the specified image.
+     *
+     * @param img the image to check
+     * @param w the target width
+     * @param h the target height
+     * @param o the image observer to notify
+     *
+     * @return the status as bitwise ORed ImageObserver flags
+     *
+     * @see Component#checkImage(Image, int, int, ImageObserver)
+     */
+    int checkImage(Image img, int w, int h, ImageObserver o);
+
+    /**
+     * Returns the graphics configuration that corresponds to this component.
+     *
+     * @return the graphics configuration that corresponds to this component
+     *
+     * @see Component#getGraphicsConfiguration()
+     */
     GraphicsConfiguration getGraphicsConfiguration();
-    boolean     handlesWheelScrolling();
-    void createBuffers(int numBuffers, BufferCapabilities caps) throws AWTException;
+
+    /**
+     * Determines if the component handles wheel scrolling itself. Otherwise
+     * it is delegated to the component's parent.
+     *
+     * @return {@code true} if the component handles wheel scrolling,
+     *         {@code false} otherwise
+     *
+     * @see Component#dispatchEventImpl(AWTEvent)
+     */
+    boolean handlesWheelScrolling();
+
+    /**
+     * Create {@code numBuffers} flipping buffers with the specified
+     * buffer capabilities.
+     *
+     * @param numBuffers the number of buffers to create
+     * @param caps the buffer capabilities
+     *
+     * @throws AWTException if flip buffering is not supported
+     *
+     * @see Component.FlipBufferStrategy#createBuffers
+     */
+    void createBuffers(int numBuffers, BufferCapabilities caps)
+         throws AWTException;
+
+    /**
+     * Returns the back buffer as image.
+     *
+     * @return the back buffer as image
+     *
+     * @see Component.FlipBufferStrategy#getBackBuffer
+     */
     Image getBackBuffer();
+
+    /**
+     * Move the back buffer to the front buffer.
+     *
+     * @param x1 the area to be flipped, upper left X coordinate
+     * @param y1 the area to be flipped, upper left Y coordinate
+     * @param x2 the area to be flipped, lower right X coordinate
+     * @param y2 the area to be flipped, lower right Y coordinate
+     * @param flipAction the flip action to perform
+     *
+     * @see Component.FlipBufferStrategy#flip
+     */
     void flip(int x1, int y1, int x2, int y2, BufferCapabilities.FlipContents flipAction);
+
+    /**
+     * Destroys all created buffers.
+     *
+     * @see Component.FlipBufferStrategy#destroyBuffers
+     */
     void destroyBuffers();
 
     /**
-     * Reparents this peer to the new parent referenced by <code>newContainer</code> peer
-     * Implementation depends on toolkit and container.
+     * Reparents this peer to the new parent referenced by
+     * {@code newContainer} peer. Implementation depends on toolkit and
+     * container.
+     *
      * @param newContainer peer of the new parent container
+     *
      * @since 1.5
      */
     void reparent(ContainerPeer newContainer);
+
     /**
-     * Returns whether this peer supports reparenting to another parent withour destroying the peer
+     * Returns whether this peer supports reparenting to another parent without
+     * destroying the peer.
+     *
      * @return true if appropriate reparent is supported, false otherwise
+     *
      * @since 1.5
      */
     boolean isReparentSupported();
@@ -108,12 +526,16 @@
      * Used by lightweight implementations to tell a ComponentPeer to layout
      * its sub-elements.  For instance, a lightweight Checkbox needs to layout
      * the box, as well as the text label.
+     *
+     * @see Component#validate()
      */
-    void        layout();
+    void layout();
 
     /**
      * Applies the shape to the native component window.
      * @since 1.7
+     *
+     * @see Component#applyCompoundShape
      */
     void applyShape(Region shape);
 
--- a/src/share/classes/java/awt/peer/ContainerPeer.java	Fri Dec 19 16:04:04 2008 +0300
+++ b/src/share/classes/java/awt/peer/ContainerPeer.java	Tue Jan 13 20:04:05 2009 +0100
@@ -27,6 +27,9 @@
 import java.awt.*;
 
 /**
+ * The peer interface for {@link Container}. This is the parent interface
+ * for all container like widgets.
+ *
  * The peer interfaces are intended only for use in porting
  * the AWT. They are not intended for use by application
  * developers, and developers should not implement peers
@@ -34,21 +37,59 @@
  * instances.
  */
 public interface ContainerPeer extends ComponentPeer {
+
+    /**
+     * Returns the insets of this container. Insets usually is the space that
+     * is occupied by things like borders.
+     *
+     * @return the insets of this container
+     */
     Insets getInsets();
+
+    /**
+     * Notifies the peer that validation of the component tree is about to
+     * begin.
+     *
+     * @see Container#validate()
+     */
     void beginValidate();
+
+    /**
+     * Notifies the peer that validation of the component tree is finished.
+     *
+     * @see Container#validate()
+     */
     void endValidate();
+
+    /**
+     * Notifies the peer that layout is about to begin. This is called
+     * before the container itself and its children are laid out.
+     *
+     * @see Container#validateTree()
+     */
     void beginLayout();
+
+    /**
+     * Notifies the peer that layout is finished. This is called after the
+     * container and its children have been laid out.
+     *
+     * @see Container#validateTree()
+     */
     void endLayout();
 
     /**
-     * Restacks native windows - children of this native window - according to Java container order
+     * Restacks native windows - children of this native window - according to
+     * Java container order.
+     *
      * @since 1.5
      */
     void restack();
 
     /**
-     * Indicates availabiltity of restacking operation in this container.
+     * Indicates availability of restacking operation in this container.
+     *
      * @return Returns true if restack is supported, false otherwise
+     *
      * @since 1.5
      */
     boolean isRestackSupported();
--- a/src/share/classes/java/awt/peer/DesktopPeer.java	Fri Dec 19 16:04:04 2008 +0300
+++ b/src/share/classes/java/awt/peer/DesktopPeer.java	Tue Jan 13 20:04:05 2009 +0100
@@ -32,7 +32,7 @@
 import java.awt.Desktop.Action;
 
 /**
- * The <code>DesktopPeer</code> interface provides methods for the operation
+ * The {@code DesktopPeer} interface provides methods for the operation
  * of open, edit, print, browse and mail with the given URL or file, by
  * launching the associated application.
  * <p>
@@ -40,14 +40,15 @@
  *
  */
 public interface DesktopPeer {
+
     /**
      * Returns whether the given action is supported on the current platform.
      * @param action the action type to be tested if it's supported on the
      *        current platform.
-     * @return <code>true</code> if the given action is supported on
-     *         the current platform; <code>false</code> otherwise.
+     * @return {@code true} if the given action is supported on
+     *         the current platform; {@code false} otherwise.
      */
-    public boolean isSupported(Action action);
+    boolean isSupported(Action action);
 
     /**
      * Launches the associated application to open the given file. The
@@ -58,7 +59,7 @@
      * @throws IOException If the given file has no associated application,
      *         or the associated application fails to be launched.
      */
-    public void open(File file) throws IOException;
+    void open(File file) throws IOException;
 
     /**
      * Launches the associated editor and opens the given file for editing. The
@@ -69,7 +70,7 @@
      * @throws IOException If the given file has no associated editor, or
      *         the associated application fails to be launched.
      */
-    public void edit(File file) throws IOException;
+    void edit(File file) throws IOException;
 
     /**
      * Prints the given file with the native desktop printing facility, using
@@ -79,7 +80,7 @@
      * @throws IOException If the given file has no associated application
      *         that can be used to print it.
      */
-    public void print(File file) throws IOException;
+    void print(File file) throws IOException;
 
     /**
      * Launches the mail composing window of the user default mail client,
@@ -93,7 +94,7 @@
      * @throws IOException If the user default mail client is not found,
      *         or it fails to be launched.
      */
-    public void mail(URI mailtoURL) throws IOException;
+    void mail(URI mailtoURL) throws IOException;
 
     /**
      * Launches the user default browser to display the given URI.
@@ -102,5 +103,5 @@
      * @throws IOException If the user default browser is not found,
      *         or it fails to be launched.
      */
-    public void browse(URI url) throws IOException;
+    void browse(URI url) throws IOException;
 }
--- a/src/share/classes/java/awt/peer/DialogPeer.java	Fri Dec 19 16:04:04 2008 +0300
+++ b/src/share/classes/java/awt/peer/DialogPeer.java	Tue Jan 13 20:04:05 2009 +0100
@@ -28,6 +28,9 @@
 import java.awt.*;
 
 /**
+ * The peer interface for {@link Dialog}. This adds a couple of dialog specific
+ * features to the {@link WindowPeer} interface.
+ *
  * The peer interfaces are intended only for use in porting
  * the AWT. They are not intended for use by application
  * developers, and developers should not implement peers
@@ -35,7 +38,33 @@
  * instances.
  */
 public interface DialogPeer extends WindowPeer {
+
+    /**
+     * Sets the title on the dialog window.
+     *
+     * @param title the title to set
+     *
+     * @see Dialog#setTitle(String)
+     */
     void setTitle(String title);
+
+    /**
+     * Sets if the dialog should be resizable or not.
+     *
+     * @param resizeable {@code true} when the dialog should be resizable,
+     *        {@code false} if not
+     *
+     * @see Dialog#setResizable(boolean)
+     */
     void setResizable(boolean resizeable);
+
+    /**
+     * Block the specified windows. This is used for modal dialogs.
+     *
+     * @param windows the windows to block
+     *
+     * @see Dialog#modalShow()
+     * @see Dialog#blockWindows()
+     */
     void blockWindows(java.util.List<Window> windows);
 }
--- a/src/share/classes/java/awt/peer/FileDialogPeer.java	Fri Dec 19 16:04:04 2008 +0300
+++ b/src/share/classes/java/awt/peer/FileDialogPeer.java	Tue Jan 13 20:04:05 2009 +0100
@@ -25,9 +25,12 @@
 
 package java.awt.peer;
 
+import java.awt.FileDialog;
 import java.io.FilenameFilter;
 
 /**
+ * The peer interface for {@link FileDialog}.
+ *
  * The peer interfaces are intended only for use in porting
  * the AWT. They are not intended for use by application
  * developers, and developers should not implement peers
@@ -35,7 +38,32 @@
  * instances.
  */
 public interface FileDialogPeer extends DialogPeer {
+
+    /**
+     * Sets the selected file for this file dialog.
+     *
+     * @param file the file to set as selected file, or {@code null} for
+     *        no selected file
+     *
+     * @see FileDialog#setFile(String)
+     */
     void setFile(String file);
+
+    /**
+     * Sets the current directory for this file dialog.
+     *
+     * @param dir the directory to set
+     *
+     * @see FileDialog#setDirectory(String)
+     */
     void setDirectory(String dir);
+
+    /**
+     * Sets the filename filter for filtering the displayed files.
+     *
+     * @param filter the filter to set
+     *
+     * @see FileDialog#setFilenameFilter(FilenameFilter)
+     */
     void setFilenameFilter(FilenameFilter filter);
 }
--- a/src/share/classes/java/awt/peer/FontPeer.java	Fri Dec 19 16:04:04 2008 +0300
+++ b/src/share/classes/java/awt/peer/FontPeer.java	Tue Jan 13 20:04:05 2009 +0100
@@ -26,6 +26,9 @@
 package java.awt.peer;
 
 /**
+ * The peer interface for fonts. This is only a marker interface and not
+ * used by AWT itself.
+ *
  * The peer interfaces are intended only for use in porting
  * the AWT. They are not intended for use by application
  * developers, and developers should not implement peers
--- a/src/share/classes/java/awt/peer/FramePeer.java	Fri Dec 19 16:04:04 2008 +0300
+++ b/src/share/classes/java/awt/peer/FramePeer.java	Tue Jan 13 20:04:05 2009 +0100
@@ -27,7 +27,12 @@
 
 import java.awt.*;
 
+import sun.awt.EmbeddedFrame;
+
 /**
+ * The peer interface for {@link Frame}. This adds a couple of frame specific
+ * methods to the {@link WindowPeer} interface.
+ *
  * The peer interfaces are intended only for use in porting
  * the AWT. They are not intended for use by application
  * developers, and developers should not implement peers
@@ -35,12 +40,89 @@
  * instances.
  */
 public interface FramePeer extends WindowPeer {
+
+    /**
+     * Sets the title on the frame.
+     *
+     * @param title the title to set
+     *
+     * @see Frame#setTitle(String)
+     */
     void setTitle(String title);
+
+    /**
+     * Sets the menu bar for the frame.
+     *
+     * @param mb the menu bar to set
+     *
+     * @see Frame#setMenuBar(MenuBar)
+     */
     void setMenuBar(MenuBar mb);
+
+    /**
+     * Sets if the frame should be resizable or not.
+     *
+     * @param resizeable {@code true} when the frame should be resizable,
+     *        {@code false} if not
+     *
+     * @see Frame#setResizable(boolean)
+     */
     void setResizable(boolean resizeable);
+
+    /**
+     * Changes the state of the frame.
+     *
+     * @param state the new state
+     *
+     * @see Frame#setExtendedState(int)
+     */
     void setState(int state);
-    int  getState();
-    void setMaximizedBounds(Rectangle bounds); // XXX
+
+    /**
+     * Returns the current state of the frame.
+     *
+     * @return the current state of the frame
+     *
+     * @see Frame#getExtendedState()
+     */
+    int getState();
+
+    /**
+     * Sets the bounds of the frame when it becomes maximized.
+     *
+     * @param bounds the maximized bounds of the frame
+     *
+     * @see Frame#setMaximizedBounds(Rectangle)
+     */
+    void setMaximizedBounds(Rectangle bounds);
+
+    /**
+     * Sets the size and location for embedded frames. (On embedded frames,
+     * setLocation() and setBounds() always set the frame to (0,0) for
+     * backwards compatibility.
+     *
+     * @param x the X location
+     * @param y the Y location
+     * @param width the width of the frame
+     * @param height the height of the frame
+     *
+     * @see EmbeddedFrame#setBoundsPrivate(int, int, int, int)
+     */
+    // TODO: This is only used in EmbeddedFrame, and should probably be moved
+    // into an EmbeddedFramePeer which would extend FramePeer
     void setBoundsPrivate(int x, int y, int width, int height);
+
+    /**
+     * Returns the size and location for embedded frames. (On embedded frames,
+     * setLocation() and setBounds() always set the frame to (0,0) for
+     * backwards compatibility.
+     *
+     * @return the bounds of an embedded frame
+     *
+     * @see EmbeddedFrame#getBoundsPrivate()
+     */
+    // TODO: This is only used in EmbeddedFrame, and should probably be moved
+    // into an EmbeddedFramePeer which would extend FramePeer
     Rectangle getBoundsPrivate();
+
 }
--- a/src/share/classes/java/awt/peer/KeyboardFocusManagerPeer.java	Fri Dec 19 16:04:04 2008 +0300
+++ b/src/share/classes/java/awt/peer/KeyboardFocusManagerPeer.java	Tue Jan 13 20:04:05 2009 +0100
@@ -28,11 +28,45 @@
 import java.awt.Component;
 import java.awt.Window;
 
+/**
+ * The native peer interface for {@link KeyboardFocusManager}.
+ */
 public interface KeyboardFocusManagerPeer {
+
+    /**
+     * Returns the currently focused window.
+     *
+     * @return the currently focused window
+     *
+     * @see KeyboardFocusManager#getNativeFocusedWindow()
+     */
     Window getCurrentFocusedWindow();
 
+    /**
+     * Sets the component that should become the focus owner.
+     *
+     * @param comp the component to become the focus owner
+     *
+     * @see KeyboardFocusManager#setNativeFocusOwner(Component)
+     */
     void setCurrentFocusOwner(Component comp);
+
+    /**
+     * Returns the component that currently owns the input focus.
+     *
+     * @return the component that currently owns the input focus
+     *
+     * @see KeyboardFocusManager#getNativeFocusOwner()
+     */
     Component getCurrentFocusOwner();
 
+    /**
+     * Clears the current global focus owner.
+     *
+     * @param activeWindow
+     *
+     * @see KeyboardFocusManager#clearGlobalFocusOwner()
+     */
     void clearGlobalFocusOwner(Window activeWindow);
+
 }
--- a/src/share/classes/java/awt/peer/LabelPeer.java	Fri Dec 19 16:04:04 2008 +0300
+++ b/src/share/classes/java/awt/peer/LabelPeer.java	Tue Jan 13 20:04:05 2009 +0100
@@ -24,7 +24,11 @@
  */
 package java.awt.peer;
 
+import java.awt.Label;
+
 /**
+ * The peer interface for {@link Label}.
+ *
  * The peer interfaces are intended only for use in porting
  * the AWT. They are not intended for use by application
  * developers, and developers should not implement peers
@@ -32,6 +36,25 @@
  * instances.
  */
 public interface LabelPeer extends ComponentPeer {
+
+    /**
+     * Sets the text to be displayed on the label.
+     *
+     * @param label the text to be displayed on the label
+     *
+     * @see Label#setText
+     */
     void setText(String label);
+
+    /**
+     * Sets the alignment of the label text.
+     *
+     * @param alignment the alignment of the label text
+     *
+     * @see Label#setAlignment(int)
+     * @see Label#CENTER
+     * @see Label#RIGHT
+     * @see Label#LEFT
+     */
     void setAlignment(int alignment);
 }
--- a/src/share/classes/java/awt/peer/ListPeer.java	Fri Dec 19 16:04:04 2008 +0300
+++ b/src/share/classes/java/awt/peer/ListPeer.java	Tue Jan 13 20:04:05 2009 +0100
@@ -25,8 +25,11 @@
 package java.awt.peer;
 
 import java.awt.Dimension;
+import java.awt.List;
 
 /**
+ * The peer interface for {@link List}.
+ *
  * The peer interfaces are intended only for use in porting
  * the AWT. They are not intended for use by application
  * developers, and developers should not implement peers
@@ -34,15 +37,102 @@
  * instances.
  */
 public interface ListPeer extends ComponentPeer {
+
+    /**
+     * Returns the indices of the list items that are currently selected.
+     * The returned array is not required to be a copy, the callers of this
+     * method already make sure it is not modified.
+     *
+     * @return the indices of the list items that are currently selected
+     *
+     * @see List#getSelectedIndexes()
+     */
     int[] getSelectedIndexes();
+
+    /**
+     * Adds an item to the list at the specified index.
+     *
+     * @param item the item to add to the list
+     * @param index the index where to add the item into the list
+     *
+     * @see List#add(String, int)
+     */
     void add(String item, int index);
+
+    /**
+     * Deletes items from the list. All items from start to end should are
+     * deleted, including the item at the start and end indices.
+     *
+     * @param start the first item to be deleted
+     * @param end the last item to be deleted
+     */
     void delItems(int start, int end);
+
+    /**
+     * Removes all items from the list.
+     *
+     * @see List#removeAll()
+     */
     void removeAll();
+
+    /**
+     * Selects the item at the specified {@code index}.
+     *
+     * @param index the index of the item to select
+     *
+     * @see List#select(int)
+     */
     void select(int index);
+
+    /**
+     * De-selects the item at the specified {@code index}.
+     *
+     * @param index the index of the item to de-select
+     *
+     * @see List#deselect(int)
+     */
     void deselect(int index);
+
+    /**
+     * Makes sure that the item at the specified {@code index} is visible,
+     * by scrolling the list or similar.
+     *
+     * @param index the index of the item to make visible
+     *
+     * @see List#makeVisible(int)
+     */
     void makeVisible(int index);
-    void setMultipleMode(boolean b);
+
+    /**
+     * Toggles multiple selection mode on or off.
+     *
+     * @param m {@code true} for multiple selection mode,
+     *        {@code false} for single selection mode
+     *
+     * @see List#setMultipleMode(boolean)
+     */
+    void setMultipleMode(boolean m);
+
+    /**
+     * Returns the preferred size for a list with the specified number of rows.
+     *
+     * @param rows the number of rows
+     *
+     * @return the preferred size of the list
+     *
+     * @see List#getPreferredSize(int)
+     */
     Dimension getPreferredSize(int rows);
+
+    /**
+     * Returns the minimum size for a list with the specified number of rows.
+     *
+     * @param rows the number of rows
+     *
+     * @return the minimum size of the list
+     *
+     * @see List#getMinimumSize(int)
+     */
     Dimension getMinimumSize(int rows);
 
 }
--- a/src/share/classes/java/awt/peer/MenuBarPeer.java	Fri Dec 19 16:04:04 2008 +0300
+++ b/src/share/classes/java/awt/peer/MenuBarPeer.java	Tue Jan 13 20:04:05 2009 +0100
@@ -25,8 +25,11 @@
 package java.awt.peer;
 
 import java.awt.Menu;
+import java.awt.MenuBar;
 
 /**
+ * The peer interface for {@link MenuBar}.
+ *
  * The peer interfaces are intended only for use in porting
  * the AWT. They are not intended for use by application
  * developers, and developers should not implement peers
@@ -34,7 +37,31 @@
  * instances.
  */
 public interface MenuBarPeer extends MenuComponentPeer {
+
+    /**
+     * Adds a menu to the menu bar.
+     *
+     * @param m the menu to add
+     *
+     * @see MenuBar#add(Menu)
+     */
     void addMenu(Menu m);
+
+    /**
+     * Deletes a menu from the menu bar.
+     *
+     * @param index the index of the menu to remove
+     *
+     * @see MenuBar#remove(int)
+     */
     void delMenu(int index);
+
+    /**
+     * Adds a help menu to the menu bar.
+     *
+     * @param m the help menu to add
+     *
+     * @see MenuBar#setHelpMenu(Menu)
+     */
     void addHelpMenu(Menu m);
 }
--- a/src/share/classes/java/awt/peer/MenuComponentPeer.java	Fri Dec 19 16:04:04 2008 +0300
+++ b/src/share/classes/java/awt/peer/MenuComponentPeer.java	Tue Jan 13 20:04:05 2009 +0100
@@ -25,8 +25,12 @@
 package java.awt.peer;
 
 import java.awt.Font;
+import java.awt.MenuComponent;
 
 /**
+ * The base interface for all kinds of menu components. This is used by
+ * {@link MenuComponent}.
+ *
  * The peer interfaces are intended only for use in porting
  * the AWT. They are not intended for use by application
  * developers, and developers should not implement peers
@@ -34,6 +38,20 @@
  * instances.
  */
 public interface MenuComponentPeer {
+
+    /**
+     * Disposes the menu component.
+     *
+     * @see MenuComponent#removeNotify()
+     */
     void dispose();
+
+    /**
+     * Sets the font for the menu component.
+     *
+     * @param f the font to use for the menu component
+     *
+     * @see MenuComponent#setFont(Font)
+     */
     void setFont(Font f);
 }
--- a/src/share/classes/java/awt/peer/MenuItemPeer.java	Fri Dec 19 16:04:04 2008 +0300
+++ b/src/share/classes/java/awt/peer/MenuItemPeer.java	Tue Jan 13 20:04:05 2009 +0100
@@ -24,7 +24,11 @@
  */
 package java.awt.peer;
 
+import java.awt.MenuItem;
+
 /**
+ * The peer interface for menu items. This is used by {@link MenuItem}.
+ *
  * The peer interfaces are intended only for use in porting
  * the AWT. They are not intended for use by application
  * developers, and developers should not implement peers
@@ -32,7 +36,20 @@
  * instances.
  */
 public interface MenuItemPeer extends MenuComponentPeer {
+
+    /**
+     * Sets the label to be displayed in this menu item.
+     *
+     * @param label the label to be displayed
+     */
     void setLabel(String label);
-    void setEnabled(boolean b);
+
+    /**
+     * Enables or disables the menu item.
+     *
+     * @param e {@code true} to enable the menu item, {@code false}
+     *        to disable it
+     */
+    void setEnabled(boolean e);
 
 }
--- a/src/share/classes/java/awt/peer/MenuPeer.java	Fri Dec 19 16:04:04 2008 +0300
+++ b/src/share/classes/java/awt/peer/MenuPeer.java	Tue Jan 13 20:04:05 2009 +0100
@@ -24,9 +24,12 @@
  */
 package java.awt.peer;
 
+import java.awt.Menu;
 import java.awt.MenuItem;
 
 /**
+ * The peer interface for menus. This is used by {@link Menu}.
+ *
  * The peer interfaces are intended only for use in porting
  * the AWT. They are not intended for use by application
  * developers, and developers should not implement peers
@@ -34,7 +37,29 @@
  * instances.
  */
 public interface MenuPeer extends MenuItemPeer {
+
+    /**
+     * Adds a separator (e.g. a horizontal line or similar) to the menu.
+     *
+     * @see Menu#addSeparator()
+     */
     void addSeparator();
+
+    /**
+     * Adds the specified menu item to the menu.
+     *
+     * @param item the menu item to add
+     *
+     * @see Menu#add(MenuItem)
+     */
     void addItem(MenuItem item);
+
+    /**
+     * Removes the menu item at the specified index.
+     *
+     * @param index the index of the item to remove
+     *
+     * @see Menu#remove(int)
+     */
     void delItem(int index);
 }
--- a/src/share/classes/java/awt/peer/MouseInfoPeer.java	Fri Dec 19 16:04:04 2008 +0300
+++ b/src/share/classes/java/awt/peer/MouseInfoPeer.java	Tue Jan 13 20:04:05 2009 +0100
@@ -29,6 +29,9 @@
 import java.awt.Point;
 
 /**
+ * Peer interface for {@link MouseInfo}. This is used to get some additional
+ * information about the mouse.
+ *
  * The peer interfaces are intended only for use in porting
  * the AWT. They are not intended for use by application
  * developers, and developers should not implement peers
--- a/src/share/classes/java/awt/peer/PanelPeer.java	Fri Dec 19 16:04:04 2008 +0300
+++ b/src/share/classes/java/awt/peer/PanelPeer.java	Tue Jan 13 20:04:05 2009 +0100
@@ -25,6 +25,10 @@
 package java.awt.peer;
 
 /**
+ * The peer interface for {@link Panel}. This is a subinterface of
+ * ContainerPeer and does not declare any additional methods because a Panel
+ * is just that, a concrete Container.
+ *
  * The peer interfaces are intended only for use in porting
  * the AWT. They are not intended for use by application
  * developers, and developers should not implement peers
--- a/src/share/classes/java/awt/peer/PopupMenuPeer.java	Fri Dec 19 16:04:04 2008 +0300
+++ b/src/share/classes/java/awt/peer/PopupMenuPeer.java	Tue Jan 13 20:04:05 2009 +0100
@@ -25,8 +25,11 @@
 package java.awt.peer;
 
 import java.awt.Event;
+import java.awt.PopupMenu;
 
 /**
+ * The peer interface for {@link PopupMenu}.
+ *
  * The peer interfaces are intended only for use in porting
  * the AWT. They are not intended for use by application
  * developers, and developers should not implement peers
@@ -34,5 +37,14 @@
  * instances.
  */
 public interface PopupMenuPeer extends MenuPeer {
+
+    /**
+     * Shows the popup menu.
+     *
+     * @param e a synthetic event describing the origin and location of the
+     *        popup menu
+     *
+     * @see PopupMenu#show(java.awt.Component, int, int)
+     */
     void show(Event e);
 }
--- a/src/share/classes/java/awt/peer/RobotPeer.java	Fri Dec 19 16:04:04 2008 +0300
+++ b/src/share/classes/java/awt/peer/RobotPeer.java	Tue Jan 13 20:04:05 2009 +0100
@@ -39,18 +39,93 @@
  */
 public interface RobotPeer
 {
-    public void mouseMove(int x, int y);
-    public void mousePress(int buttons);
-    public void mouseRelease(int buttons);
+    /**
+     * Moves the mouse pointer to the specified screen location.
+     *
+     * @param x the X location on screen
+     * @param y the Y location on screen
+     *
+     * @see Robot#mouseMove(int, int)
+     */
+    void mouseMove(int x, int y);
 
-    public void mouseWheel(int wheelAmt);
+    /**
+     * Simulates a mouse press with the specified button(s).
+     *
+     * @param buttons the button mask
+     *
+     * @see Robot#mousePress(int)
+     */
+    void mousePress(int buttons);
 
-    public void keyPress(int keycode);
-    public void keyRelease(int keycode);
+    /**
+     * Simulates a mouse release with the specified button(s).
+     *
+     * @param buttons the button mask
+     *
+     * @see Robot#mouseRelease(int)
+     */
+    void mouseRelease(int buttons);
 
-    public int getRGBPixel(int x, int y);
-    public int [] getRGBPixels(Rectangle bounds);
+    /**
+     * Simulates mouse wheel action.
+     *
+     * @param wheelAmt number of notches to move the mouse wheel
+     *
+     * @see Robot#mouseWheel(int)
+     */
+    void mouseWheel(int wheelAmt);
 
-    public void dispose();
-    public int getNumberOfButtons();
+    /**
+     * Simulates a key press of the specified key.
+     *
+     * @param keycode the key code to press
+     *
+     * @see Robot#keyPress(int)
+     */
+    void keyPress(int keycode);
+
+    /**
+     * Simulates a key release of the specified key.
+     *
+     * @param keycode the key code to release
+     *
+     * @see Robot#keyRelease(int)
+     */
+    void keyRelease(int keycode);
+
+    /**
+     * Gets the RGB value of the specified pixel on screen.
+     *
+     * @param x the X screen coordinate
+     * @param y the Y screen coordinate
+     *
+     * @return the RGB value of the specified pixel on screen
+     *
+     * @see Robot#getPixelColor(int, int)
+     */
+    int getRGBPixel(int x, int y);
+
+    /**
+     * Gets the RGB values of the specified screen area as an array.
+     *
+     * @param bounds the screen area to capture the RGB values from
+     *
+     * @return the RGB values of the specified screen area
+     *
+     * @see Robot#createScreenCapture(Rectangle)
+     */
+    int[] getRGBPixels(Rectangle bounds);
+
+    /**
+     * Disposes the robot peer when it is not needed anymore.
+     */
+    void dispose();
+
+    /**
+     * Returns the number of buttons that the robot simulates.
+     *
+     * @return the number of buttons that the robot simulates
+     */
+    int getNumberOfButtons();
 }
--- a/src/share/classes/java/awt/peer/ScrollPanePeer.java	Fri Dec 19 16:04:04 2008 +0300
+++ b/src/share/classes/java/awt/peer/ScrollPanePeer.java	Tue Jan 13 20:04:05 2009 +0100
@@ -25,8 +25,12 @@
 package java.awt.peer;
 
 import java.awt.Adjustable;
+import java.awt.ScrollPane;
+import java.awt.ScrollPaneAdjustable;
 
 /**
+ * The peer interface for {@link ScrollPane}.
+ *
  * The peer interfaces are intended only for use in porting
  * the AWT. They are not intended for use by application
  * developers, and developers should not implement peers
@@ -34,10 +38,60 @@
  * instances.
  */
 public interface ScrollPanePeer extends ContainerPeer {
+
+    /**
+     * Returns the height of the horizontal scroll bar.
+     *
+     * @return the height of the horizontal scroll bar
+     *
+     * @see ScrollPane#getHScrollbarHeight()
+     */
     int getHScrollbarHeight();
+
+    /**
+     * Returns the width of the vertical scroll bar.
+     *
+     * @return the width of the vertical scroll bar
+     *
+     * @see ScrollPane#getVScrollbarWidth()
+     */
     int getVScrollbarWidth();
+
+    /**
+     * Sets the scroll position of the child.
+     *
+     * @param x the X coordinate of the scroll position
+     * @param y the Y coordinate of the scroll position
+     *
+     * @see ScrollPane#setScrollPosition(int, int)
+     */
     void setScrollPosition(int x, int y);
+
+    /**
+     * Called when the child component changes its size.
+     *
+     * @param w the new width of the child component
+     * @param h the new height of the child component
+     *
+     * @see ScrollPane#layout()
+     */
     void childResized(int w, int h);
+
+    /**
+     * Sets the unit increment of one of the scroll pane's adjustables.
+     *
+     * @param adj the scroll pane adjustable object
+     * @param u the unit increment
+     *
+     * @see ScrollPaneAdjustable#setUnitIncrement(int)
+     */
     void setUnitIncrement(Adjustable adj, int u);
+
+    /**
+     * Sets the value for one of the scroll pane's adjustables.
+     *
+     * @param adj the scroll pane adjustable object
+     * @param v the value to set
+     */
     void setValue(Adjustable adj, int v);
 }
--- a/src/share/classes/java/awt/peer/ScrollbarPeer.java	Fri Dec 19 16:04:04 2008 +0300
+++ b/src/share/classes/java/awt/peer/ScrollbarPeer.java	Tue Jan 13 20:04:05 2009 +0100
@@ -24,7 +24,11 @@
  */
 package java.awt.peer;
 
+import java.awt.Scrollbar;
+
 /**
+ * The peer interface for {@link Scrollbar}.
+ *
  * The peer interfaces are intended only for use in porting
  * the AWT. They are not intended for use by application
  * developers, and developers should not implement peers
@@ -32,7 +36,34 @@
  * instances.
  */
 public interface ScrollbarPeer extends ComponentPeer {
+
+    /**
+     * Sets the parameters for the scrollbar.
+     *
+     * @param value the current value
+     * @param visible how much of the whole scale is visible
+     * @param minimum the minimum value
+     * @param maximum the maximum value
+     *
+     * @see Scrollbar#setValues(int, int, int, int)
+     */
     void setValues(int value, int visible, int minimum, int maximum);
+
+    /**
+     * Sets the line increment of the scrollbar.
+     *
+     * @param l the line increment
+     *
+     * @see Scrollbar#setLineIncrement(int)
+     */
     void setLineIncrement(int l);
+
+    /**
+     * Sets the page increment of the scrollbar.
+     *
+     * @param l the page increment
+     *
+     * @see Scrollbar#setPageIncrement(int)
+     */
     void setPageIncrement(int l);
 }
--- a/src/share/classes/java/awt/peer/SystemTrayPeer.java	Fri Dec 19 16:04:04 2008 +0300
+++ b/src/share/classes/java/awt/peer/SystemTrayPeer.java	Tue Jan 13 20:04:05 2009 +0100
@@ -26,7 +26,20 @@
 package java.awt.peer;
 
 import java.awt.Dimension;
+import java.awt.SystemTray;
 
+/**
+ * The peer interface for {@link SystemTray}. This doesn't need to be
+ * implemented if {@link SystemTray#isSupported()} returns false.
+ */
 public interface SystemTrayPeer {
+
+    /**
+     * Returns the size of the system tray icon.
+     *
+     * @return the size of the system tray icon
+     *
+     * @see SystemTray#getTrayIconSize()
+     */
     Dimension getTrayIconSize();
 }
--- a/src/share/classes/java/awt/peer/TextAreaPeer.java	Fri Dec 19 16:04:04 2008 +0300
+++ b/src/share/classes/java/awt/peer/TextAreaPeer.java	Tue Jan 13 20:04:05 2009 +0100
@@ -25,8 +25,11 @@
 package java.awt.peer;
 
 import java.awt.Dimension;
+import java.awt.TextArea;
 
 /**
+ * The peer interface for {@link TexTArea}.
+ *
  * The peer interfaces are intended only for use in porting
  * the AWT. They are not intended for use by application
  * developers, and developers should not implement peers
@@ -34,9 +37,52 @@
  * instances.
  */
 public interface TextAreaPeer extends TextComponentPeer {
+
+    /**
+     * Inserts the specified text at the specified position in the document.
+     *
+     * @param text the text to insert
+     * @param pos the position to insert
+     *
+     * @see TextArea#insert(String, int)
+     */
     void insert(String text, int pos);
+
+    /**
+     * Replaces a range of text by the specified string
+     *
+     * @param text the replacement string
+     * @param start the begin of the range to replace
+     * @param end the end of the range to replace
+     *
+     * @see TextArea#replaceRange(String, int, int)
+     */
     void replaceRange(String text, int start, int end);
+
+    /**
+     * Returns the preferred size of a textarea with the specified number of
+     * columns and rows.
+     *
+     * @param rows the number of rows
+     * @param columns the number of columns
+     *
+     * @return the preferred size of a textarea
+     *
+     * @see TextArea#getPreferredSize(int, int)
+     */
     Dimension getPreferredSize(int rows, int columns);
+
+    /**
+     * Returns the minimum size of a textarea with the specified number of
+     * columns and rows.
+     *
+     * @param rows the number of rows
+     * @param columns the number of columns
+     *
+     * @return the minimum size of a textarea
+     *
+     * @see TextArea#getMinimumSize(int, int)
+     */
     Dimension getMinimumSize(int rows, int columns);
 
 }
--- a/src/share/classes/java/awt/peer/TextComponentPeer.java	Fri Dec 19 16:04:04 2008 +0300
+++ b/src/share/classes/java/awt/peer/TextComponentPeer.java	Tue Jan 13 20:04:05 2009 +0100
@@ -24,9 +24,12 @@
  */
 package java.awt.peer;
 
+import java.awt.TextComponent;
 import java.awt.im.InputMethodRequests;
 
 /**
+ * The peer interface for {@link TextComponent}.
+ *
  * The peer interfaces are intended only for use in porting
  * the AWT. They are not intended for use by application
  * developers, and developers should not implement peers
@@ -34,13 +37,85 @@
  * instances.
  */
 public interface TextComponentPeer extends ComponentPeer {
+
+    /**
+     * Sets if the text component should be editable or not.
+     *
+     * @param editable {@code true} for editable text components,
+     *        {@code false} for non-editable text components
+     *
+     * @see TextComponent#setEditable(boolean)
+     */
     void setEditable(boolean editable);
+
+    /**
+     * Returns the current content of the text component.
+     *
+     * @return the current content of the text component
+     *
+     * @see TextComponent#getText()
+     */
     String getText();
+
+    /**
+     * Sets the content for the text component.
+     *
+     * @param l the content to set
+     *
+     * @see TextComponent#setText(String)
+     */
     void setText(String l);
+
+    /**
+     * Returns the start index of the current selection.
+     *
+     * @return the start index of the current selection
+     *
+     * @see TextComponent#getSelectionStart()
+     */
     int getSelectionStart();
+
+    /**
+     * Returns the end index of the current selection.
+     *
+     * @return the end index of the current selection
+     *
+     * @see TextComponent#getSelectionEnd()
+     */
     int getSelectionEnd();
+
+    /**
+     * Selects an area of the text component.
+     *
+     * @param selStart the start index of the new selection
+     * @param selEnd the end index of the new selection
+     *
+     * @see TextComponent#select(int, int)
+     */
     void select(int selStart, int selEnd);
+
+    /**
+     * Sets the caret position of the text component.
+     *
+     * @param pos the caret position to set
+     *
+     * @see TextComponent#setCaretPosition(int)
+     */
     void setCaretPosition(int pos);
+
+    /**
+     * Returns the current caret position.
+     *
+     * @return the current caret position
+     *
+     * @see TextComponent#getCaretPosition()
+     */
     int getCaretPosition();
+
+    /**
+     * Returns the input method requests.
+     *
+     * @return the input method requests
+     */
     InputMethodRequests getInputMethodRequests();
 }
--- a/src/share/classes/java/awt/peer/TextFieldPeer.java	Fri Dec 19 16:04:04 2008 +0300
+++ b/src/share/classes/java/awt/peer/TextFieldPeer.java	Tue Jan 13 20:04:05 2009 +0100
@@ -25,8 +25,11 @@
 package java.awt.peer;
 
 import java.awt.Dimension;
+import java.awt.TextField;
 
 /**
+ * The peer interface for {@link TextField}.
+ *
  * The peer interfaces are intended only for use in porting
  * the AWT. They are not intended for use by application
  * developers, and developers should not implement peers
@@ -34,8 +37,38 @@
  * instances.
  */
 public interface TextFieldPeer extends TextComponentPeer {
+
+    /**
+     * Sets the echo character.
+     *
+     * @param echoChar the echo character to set
+     *
+     * @see TextField#getEchoChar()
+     */
     void setEchoChar(char echoChar);
+
+    /**
+     * Returns the preferred size of the text field with the specified number
+     * of columns.
+     *
+     * @param columns the number of columns
+     *
+     * @return the preferred size of the text field
+     *
+     * @see TextField#getPreferredSize(int)
+     */
     Dimension getPreferredSize(int columns);
+
+    /**
+     * Returns the minimum size of the text field with the specified number
+     * of columns.
+     *
+     * @param columns the number of columns
+     *
+     * @return the minimum size of the text field
+     *
+     * @see TextField#getMinimumSize(int)
+     */
     Dimension getMinimumSize(int columns);
 
 }
--- a/src/share/classes/java/awt/peer/TrayIconPeer.java	Fri Dec 19 16:04:04 2008 +0300
+++ b/src/share/classes/java/awt/peer/TrayIconPeer.java	Tue Jan 13 20:04:05 2009 +0100
@@ -25,10 +25,56 @@
 
 package java.awt.peer;
 
+import java.awt.SystemTray;
+import java.awt.TrayIcon;
+
+/**
+ * The peer interface for the {@link TrayIcon}. This doesn't need to be
+ * implemented if {@link SystemTray#isSupported()} returns false.
+ */
 public interface TrayIconPeer {
+
+    /**
+     * Disposes the tray icon and releases and resources held by it.
+     *
+     * @see TrayIcon#removeNotify()
+     */
     void dispose();
+
+    /**
+     * Sets the tool tip for the tray icon.
+     *
+     * @param tooltip the tooltip to set
+     *
+     * @see TrayIcon#setToolTip(String)
+     */
     void setToolTip(String tooltip);
+
+    /**
+     * Updates the icon image. This is supposed to display the current icon
+     * from the TrayIcon component in the actual tray icon.
+     *
+     * @see TrayIcon#setImage(java.awt.Image)
+     * @see TrayIcon#setImageAutoSize(boolean)
+     */
     void updateImage();
+
+    /**
+     * Displays a message at the tray icon.
+     *
+     * @param caption the message caption
+     * @param text the actual message text
+     * @param messageType the message type
+     *
+     * @see TrayIcon#displayMessage(String, String, java.awt.TrayIcon.MessageType)
+     */
     void displayMessage(String caption, String text, String messageType);
+
+    /**
+     * Shows the popup menu of this tray icon at the specified position.
+     *
+     * @param x the X location for the popup menu
+     * @param y the Y location for the popup menu
+     */
     void showPopupMenu(int x, int y);
 }
--- a/src/share/classes/java/awt/peer/WindowPeer.java	Fri Dec 19 16:04:04 2008 +0300
+++ b/src/share/classes/java/awt/peer/WindowPeer.java	Tue Jan 13 20:04:05 2009 +0100
@@ -28,6 +28,8 @@
 import java.awt.*;
 
 /**
+ * The peer interface for {@link Window}.
+ *
  * The peer interfaces are intended only for use in porting
  * the AWT. They are not intended for use by application
  * developers, and developers should not implement peers
@@ -35,11 +37,59 @@
  * instances.
  */
 public interface WindowPeer extends ContainerPeer {
+
+    /**
+     * Makes this window the topmost window on the desktop.
+     *
+     * @see Window#toFront()
+     */
     void toFront();
+
+    /**
+     * Makes this window the bottommost window on the desktop.
+     *
+     * @see Window#toBack()
+     */
     void toBack();
+
+    /**
+     * Sets if the window should always stay on top of all other windows or
+     * not.
+     *
+     * @param alwaysOnTop if the window should always stay on top of all other
+     *        windows or not
+     *
+     * @see Window#setAlwaysOnTop(boolean)
+     */
     void setAlwaysOnTop(boolean alwaysOnTop);
+
+    /**
+     * Updates the window's focusable state.
+     *
+     * @see Window#setFocusableWindowState(boolean)
+     */
     void updateFocusableWindowState();
+
+    /**
+     * Sets if this window is blocked by a modal dialog or not.
+     *
+     * @param blocker the blocking modal dialog
+     * @param blocked {@code true} to block the window, {@code false}
+     *        to unblock it
+     */
     void setModalBlocked(Dialog blocker, boolean blocked);
+
+    /**
+     * Updates the minimum size on the peer.
+     *
+     * @see Window#setMinimumSize(Dimension)
+     */
     void updateMinimumSize();
+
+    /**
+     * Updates the icons for the window.
+     *
+     * @see Window#setIconImages(java.util.List)
+     */
     void updateIconImages();
 }