From 825d9ee98530a01cee857ce965a8109ee9acefe6 Mon Sep 17 00:00:00 2001 From: Alexander Stepanov Date: Tue, 24 Jun 2014 16:57:02 +0400 Subject: [PATCH] 8043967: Fix doclint warnings for java.awt Reviewed-by: pchelko --- jdk/src/share/classes/java/awt/AWTEvent.java | 7 +- .../classes/java/awt/AWTEventMulticaster.java | 81 ++++++++- .../share/classes/java/awt/AWTKeyStroke.java | 1 + .../classes/java/awt/AlphaComposite.java | 6 +- .../share/classes/java/awt/BorderLayout.java | 8 +- jdk/src/share/classes/java/awt/Button.java | 4 +- jdk/src/share/classes/java/awt/Checkbox.java | 5 +- .../share/classes/java/awt/CheckboxGroup.java | 11 +- jdk/src/share/classes/java/awt/Choice.java | 15 +- jdk/src/share/classes/java/awt/Component.java | 157 +++++++++++++++++- .../java/awt/ComponentOrientation.java | 10 +- jdk/src/share/classes/java/awt/Container.java | 17 +- jdk/src/share/classes/java/awt/Cursor.java | 7 +- .../share/classes/java/awt/DisplayMode.java | 4 +- .../share/classes/java/awt/EventQueue.java | 3 + jdk/src/share/classes/java/awt/Frame.java | 8 +- .../classes/java/awt/GraphicsEnvironment.java | 2 + .../share/classes/java/awt/GridBagLayout.java | 39 +++-- .../classes/java/awt/HeadlessException.java | 16 +- .../classes/java/awt/ItemSelectable.java | 4 +- .../java/awt/KeyboardFocusManager.java | 2 + jdk/src/share/classes/java/awt/Label.java | 6 +- .../share/classes/java/awt/LayoutManager.java | 11 +- .../classes/java/awt/LayoutManager2.java | 12 +- jdk/src/share/classes/java/awt/List.java | 60 ++++++- .../share/classes/java/awt/MediaTracker.java | 10 +- jdk/src/share/classes/java/awt/Menu.java | 7 +- jdk/src/share/classes/java/awt/MenuBar.java | 14 +- .../share/classes/java/awt/MenuComponent.java | 3 +- .../share/classes/java/awt/MenuContainer.java | 17 +- jdk/src/share/classes/java/awt/MenuItem.java | 15 +- .../share/classes/java/awt/PrintGraphics.java | 4 +- jdk/src/share/classes/java/awt/PrintJob.java | 10 +- jdk/src/share/classes/java/awt/Robot.java | 15 +- .../share/classes/java/awt/ScrollPane.java | 9 +- jdk/src/share/classes/java/awt/Scrollbar.java | 19 ++- jdk/src/share/classes/java/awt/TextArea.java | 31 +++- .../share/classes/java/awt/TextComponent.java | 5 +- jdk/src/share/classes/java/awt/TextField.java | 22 ++- jdk/src/share/classes/java/awt/Toolkit.java | 26 ++- jdk/src/share/classes/java/awt/Window.java | 11 +- 41 files changed, 634 insertions(+), 80 deletions(-) diff --git a/jdk/src/share/classes/java/awt/AWTEvent.java b/jdk/src/share/classes/java/awt/AWTEvent.java index db51f2c1088..4a935f39848 100644 --- a/jdk/src/share/classes/java/awt/AWTEvent.java +++ b/jdk/src/share/classes/java/awt/AWTEvent.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1996, 2014, Oracle and/or its affiliates. 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 @@ -388,6 +388,8 @@ public abstract class AWTEvent extends EventObject { /** * Returns the event type. + * + * @return the event's type id */ public int getID() { return id; @@ -446,6 +448,9 @@ public abstract class AWTEvent extends EventObject { /** * Returns whether this event has been consumed. + * + * @return {@code true} if this event has been consumed; + * otherwise {@code false} */ protected boolean isConsumed() { return consumed; diff --git a/jdk/src/share/classes/java/awt/AWTEventMulticaster.java b/jdk/src/share/classes/java/awt/AWTEventMulticaster.java index de51ab1c0b4..112dbb62ace 100644 --- a/jdk/src/share/classes/java/awt/AWTEventMulticaster.java +++ b/jdk/src/share/classes/java/awt/AWTEventMulticaster.java @@ -110,7 +110,15 @@ public class AWTEventMulticaster implements TextListener, InputMethodListener, HierarchyListener, HierarchyBoundsListener, MouseWheelListener { - protected final EventListener a, b; + /** + * A variable in the event chain (listener-a) + */ + protected final EventListener a; + + /** + * A variable in the event chain (listener-b) + */ + protected final EventListener b; /** * Creates an event multicaster instance which chains listener-a @@ -537,6 +545,7 @@ public class AWTEventMulticaster implements * returns the resulting multicast listener. * @param a component-listener-a * @param b component-listener-b + * @return the resulting listener */ public static ComponentListener add(ComponentListener a, ComponentListener b) { return (ComponentListener)addInternal(a, b); @@ -547,6 +556,7 @@ public class AWTEventMulticaster implements * returns the resulting multicast listener. * @param a container-listener-a * @param b container-listener-b + * @return the resulting listener */ public static ContainerListener add(ContainerListener a, ContainerListener b) { return (ContainerListener)addInternal(a, b); @@ -557,6 +567,7 @@ public class AWTEventMulticaster implements * returns the resulting multicast listener. * @param a focus-listener-a * @param b focus-listener-b + * @return the resulting listener */ public static FocusListener add(FocusListener a, FocusListener b) { return (FocusListener)addInternal(a, b); @@ -567,6 +578,7 @@ public class AWTEventMulticaster implements * returns the resulting multicast listener. * @param a key-listener-a * @param b key-listener-b + * @return the resulting listener */ public static KeyListener add(KeyListener a, KeyListener b) { return (KeyListener)addInternal(a, b); @@ -577,6 +589,7 @@ public class AWTEventMulticaster implements * returns the resulting multicast listener. * @param a mouse-listener-a * @param b mouse-listener-b + * @return the resulting listener */ public static MouseListener add(MouseListener a, MouseListener b) { return (MouseListener)addInternal(a, b); @@ -587,6 +600,7 @@ public class AWTEventMulticaster implements * returns the resulting multicast listener. * @param a mouse-motion-listener-a * @param b mouse-motion-listener-b + * @return the resulting listener */ public static MouseMotionListener add(MouseMotionListener a, MouseMotionListener b) { return (MouseMotionListener)addInternal(a, b); @@ -597,6 +611,7 @@ public class AWTEventMulticaster implements * returns the resulting multicast listener. * @param a window-listener-a * @param b window-listener-b + * @return the resulting listener */ public static WindowListener add(WindowListener a, WindowListener b) { return (WindowListener)addInternal(a, b); @@ -607,6 +622,7 @@ public class AWTEventMulticaster implements * and returns the resulting multicast listener. * @param a window-state-listener-a * @param b window-state-listener-b + * @return the resulting listener * @since 1.4 */ @SuppressWarnings("overloads") @@ -620,6 +636,7 @@ public class AWTEventMulticaster implements * and returns the resulting multicast listener. * @param a window-focus-listener-a * @param b window-focus-listener-b + * @return the resulting listener * @since 1.4 */ public static WindowFocusListener add(WindowFocusListener a, @@ -632,6 +649,7 @@ public class AWTEventMulticaster implements * returns the resulting multicast listener. * @param a action-listener-a * @param b action-listener-b + * @return the resulting listener */ @SuppressWarnings("overloads") public static ActionListener add(ActionListener a, ActionListener b) { @@ -643,6 +661,7 @@ public class AWTEventMulticaster implements * returns the resulting multicast listener. * @param a item-listener-a * @param b item-listener-b + * @return the resulting listener */ @SuppressWarnings("overloads") public static ItemListener add(ItemListener a, ItemListener b) { @@ -654,11 +673,21 @@ public class AWTEventMulticaster implements * returns the resulting multicast listener. * @param a adjustment-listener-a * @param b adjustment-listener-b + * @return the resulting listener */ @SuppressWarnings("overloads") public static AdjustmentListener add(AdjustmentListener a, AdjustmentListener b) { return (AdjustmentListener)addInternal(a, b); } + + /** + * Adds text-listener-a with text-listener-b and + * returns the resulting multicast listener. + * + * @param a text-listener-a + * @param b text-listener-b + * @return the resulting listener + */ @SuppressWarnings("overloads") public static TextListener add(TextListener a, TextListener b) { return (TextListener)addInternal(a, b); @@ -669,6 +698,7 @@ public class AWTEventMulticaster implements * returns the resulting multicast listener. * @param a input-method-listener-a * @param b input-method-listener-b + * @return the resulting listener */ public static InputMethodListener add(InputMethodListener a, InputMethodListener b) { return (InputMethodListener)addInternal(a, b); @@ -679,6 +709,7 @@ public class AWTEventMulticaster implements * returns the resulting multicast listener. * @param a hierarchy-listener-a * @param b hierarchy-listener-b + * @return the resulting listener * @since 1.3 */ @SuppressWarnings("overloads") @@ -691,6 +722,7 @@ public class AWTEventMulticaster implements * returns the resulting multicast listener. * @param a hierarchy-bounds-listener-a * @param b hierarchy-bounds-listener-b + * @return the resulting listener * @since 1.3 */ public static HierarchyBoundsListener add(HierarchyBoundsListener a, HierarchyBoundsListener b) { @@ -702,6 +734,7 @@ public class AWTEventMulticaster implements * returns the resulting multicast listener. * @param a mouse-wheel-listener-a * @param b mouse-wheel-listener-b + * @return the resulting listener * @since 1.4 */ @SuppressWarnings("overloads") @@ -715,6 +748,7 @@ public class AWTEventMulticaster implements * returns the resulting multicast listener. * @param l component-listener-l * @param oldl the component-listener being removed + * @return the resulting listener */ public static ComponentListener remove(ComponentListener l, ComponentListener oldl) { return (ComponentListener) removeInternal(l, oldl); @@ -725,6 +759,7 @@ public class AWTEventMulticaster implements * returns the resulting multicast listener. * @param l container-listener-l * @param oldl the container-listener being removed + * @return the resulting listener */ public static ContainerListener remove(ContainerListener l, ContainerListener oldl) { return (ContainerListener) removeInternal(l, oldl); @@ -735,6 +770,7 @@ public class AWTEventMulticaster implements * returns the resulting multicast listener. * @param l focus-listener-l * @param oldl the focus-listener being removed + * @return the resulting listener */ public static FocusListener remove(FocusListener l, FocusListener oldl) { return (FocusListener) removeInternal(l, oldl); @@ -745,6 +781,7 @@ public class AWTEventMulticaster implements * returns the resulting multicast listener. * @param l key-listener-l * @param oldl the key-listener being removed + * @return the resulting listener */ public static KeyListener remove(KeyListener l, KeyListener oldl) { return (KeyListener) removeInternal(l, oldl); @@ -755,6 +792,7 @@ public class AWTEventMulticaster implements * returns the resulting multicast listener. * @param l mouse-listener-l * @param oldl the mouse-listener being removed + * @return the resulting listener */ public static MouseListener remove(MouseListener l, MouseListener oldl) { return (MouseListener) removeInternal(l, oldl); @@ -765,6 +803,7 @@ public class AWTEventMulticaster implements * and returns the resulting multicast listener. * @param l mouse-motion-listener-l * @param oldl the mouse-motion-listener being removed + * @return the resulting listener */ public static MouseMotionListener remove(MouseMotionListener l, MouseMotionListener oldl) { return (MouseMotionListener) removeInternal(l, oldl); @@ -775,6 +814,7 @@ public class AWTEventMulticaster implements * returns the resulting multicast listener. * @param l window-listener-l * @param oldl the window-listener being removed + * @return the resulting listener */ public static WindowListener remove(WindowListener l, WindowListener oldl) { return (WindowListener) removeInternal(l, oldl); @@ -785,6 +825,7 @@ public class AWTEventMulticaster implements * and returns the resulting multicast listener. * @param l window-state-listener-l * @param oldl the window-state-listener being removed + * @return the resulting listener * @since 1.4 */ @SuppressWarnings("overloads") @@ -798,6 +839,7 @@ public class AWTEventMulticaster implements * and returns the resulting multicast listener. * @param l window-focus-listener-l * @param oldl the window-focus-listener being removed + * @return the resulting listener * @since 1.4 */ public static WindowFocusListener remove(WindowFocusListener l, @@ -810,6 +852,7 @@ public class AWTEventMulticaster implements * returns the resulting multicast listener. * @param l action-listener-l * @param oldl the action-listener being removed + * @return the resulting listener */ @SuppressWarnings("overloads") public static ActionListener remove(ActionListener l, ActionListener oldl) { @@ -821,6 +864,7 @@ public class AWTEventMulticaster implements * returns the resulting multicast listener. * @param l item-listener-l * @param oldl the item-listener being removed + * @return the resulting listener */ @SuppressWarnings("overloads") public static ItemListener remove(ItemListener l, ItemListener oldl) { @@ -832,11 +876,21 @@ public class AWTEventMulticaster implements * returns the resulting multicast listener. * @param l adjustment-listener-l * @param oldl the adjustment-listener being removed + * @return the resulting listener */ @SuppressWarnings("overloads") public static AdjustmentListener remove(AdjustmentListener l, AdjustmentListener oldl) { return (AdjustmentListener) removeInternal(l, oldl); } + + /** + * Removes the old text-listener from text-listener-l and + * returns the resulting multicast listener. + * + * @param l text-listener-l + * @param oldl the text-listener being removed + * @return the resulting listener + */ @SuppressWarnings("overloads") public static TextListener remove(TextListener l, TextListener oldl) { return (TextListener) removeInternal(l, oldl); @@ -847,6 +901,7 @@ public class AWTEventMulticaster implements * returns the resulting multicast listener. * @param l input-method-listener-l * @param oldl the input-method-listener being removed + * @return the resulting listener */ public static InputMethodListener remove(InputMethodListener l, InputMethodListener oldl) { return (InputMethodListener) removeInternal(l, oldl); @@ -857,6 +912,7 @@ public class AWTEventMulticaster implements * returns the resulting multicast listener. * @param l hierarchy-listener-l * @param oldl the hierarchy-listener being removed + * @return the resulting listener * @since 1.3 */ @SuppressWarnings("overloads") @@ -870,6 +926,7 @@ public class AWTEventMulticaster implements * listener. * @param l hierarchy-bounds-listener-l * @param oldl the hierarchy-bounds-listener being removed + * @return the resulting listener * @since 1.3 */ public static HierarchyBoundsListener remove(HierarchyBoundsListener l, HierarchyBoundsListener oldl) { @@ -881,6 +938,7 @@ public class AWTEventMulticaster implements * and returns the resulting multicast listener. * @param l mouse-wheel-listener-l * @param oldl the mouse-wheel-listener being removed + * @return the resulting listener * @since 1.4 */ @SuppressWarnings("overloads") @@ -898,6 +956,7 @@ public class AWTEventMulticaster implements * a new AWTEventMulticaster instance which chains a with b. * @param a event listener-a * @param b event listener-b + * @return the resulting listener */ protected static EventListener addInternal(EventListener a, EventListener b) { if (a == null) return b; @@ -915,6 +974,7 @@ public class AWTEventMulticaster implements * Else, returns listener l. * @param l the listener being removed from * @param oldl the listener being removed + * @return the resulting listener */ protected static EventListener removeInternal(EventListener l, EventListener oldl) { if (l == oldl || l == null) { @@ -927,9 +987,14 @@ public class AWTEventMulticaster implements } - /* Serialization support. - */ - + /** + * Serialization support. Saves all Serializable listeners + * to a serialization stream. + * + * @param s the stream to save to + * @param k a prefix stream to put before each serializable listener + * @throws IOException if serialization fails + */ protected void saveInternal(ObjectOutputStream s, String k) throws IOException { if (a instanceof AWTEventMulticaster) { ((AWTEventMulticaster)a).saveInternal(s, k); @@ -948,6 +1013,14 @@ public class AWTEventMulticaster implements } } + /** + * Saves a Serializable listener chain to a serialization stream. + * + * @param s the stream to save to + * @param k a prefix stream to put before each serializable listener + * @param l the listener chain to save + * @throws IOException if serialization fails + */ protected static void save(ObjectOutputStream s, String k, EventListener l) throws IOException { if (l == null) { return; diff --git a/jdk/src/share/classes/java/awt/AWTKeyStroke.java b/jdk/src/share/classes/java/awt/AWTKeyStroke.java index 4be729b8c89..681113a07db 100644 --- a/jdk/src/share/classes/java/awt/AWTKeyStroke.java +++ b/jdk/src/share/classes/java/awt/AWTKeyStroke.java @@ -802,6 +802,7 @@ public class AWTKeyStroke implements Serializable { * AWTKeyStroke) which is equal to this instance. * * @return a cached instance which is equal to this instance + * @throws java.io.ObjectStreamException if a serialization problem occurs */ protected Object readResolve() throws java.io.ObjectStreamException { synchronized (AWTKeyStroke.class) { diff --git a/jdk/src/share/classes/java/awt/AlphaComposite.java b/jdk/src/share/classes/java/awt/AlphaComposite.java index f08ea2b47bf..542d2884a01 100644 --- a/jdk/src/share/classes/java/awt/AlphaComposite.java +++ b/jdk/src/share/classes/java/awt/AlphaComposite.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1997, 2014, Oracle and/or its affiliates. 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 @@ -621,7 +621,9 @@ public final class AlphaComposite implements Composite { /** * Creates an AlphaComposite object with the specified rule. + * * @param rule the compositing rule + * @return the {@code AlphaComposite} object created * @throws IllegalArgumentException if rule is not one of * the following: {@link #CLEAR}, {@link #SRC}, {@link #DST}, * {@link #SRC_OVER}, {@link #DST_OVER}, {@link #SRC_IN}, @@ -664,10 +666,12 @@ public final class AlphaComposite implements Composite { * the constant alpha to multiply with the alpha of the source. * The source is multiplied with the specified alpha before being composited * with the destination. + * * @param rule the compositing rule * @param alpha the constant alpha to be multiplied with the alpha of * the source. alpha must be a floating point number in the * inclusive range [0.0, 1.0]. + * @return the {@code AlphaComposite} object created * @throws IllegalArgumentException if * alpha is less than 0.0 or greater than 1.0, or if * rule is not one of diff --git a/jdk/src/share/classes/java/awt/BorderLayout.java b/jdk/src/share/classes/java/awt/BorderLayout.java index b2f7e25fe19..fd891bc371b 100644 --- a/jdk/src/share/classes/java/awt/BorderLayout.java +++ b/jdk/src/share/classes/java/awt/BorderLayout.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1995, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1995, 2014, Oracle and/or its affiliates. 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 @@ -367,6 +367,8 @@ public class BorderLayout implements LayoutManager2, /** * Returns the horizontal gap between components. + * + * @return the horizontal gap between components * @since 1.1 */ public int getHgap() { @@ -375,6 +377,7 @@ public class BorderLayout implements LayoutManager2, /** * Sets the horizontal gap between components. + * * @param hgap the horizontal gap between components * @since 1.1 */ @@ -384,6 +387,8 @@ public class BorderLayout implements LayoutManager2, /** * Returns the vertical gap between components. + * + * @return the vertical gap between components * @since 1.1 */ public int getVgap() { @@ -392,6 +397,7 @@ public class BorderLayout implements LayoutManager2, /** * Sets the vertical gap between components. + * * @param vgap the vertical gap between components * @since 1.1 */ diff --git a/jdk/src/share/classes/java/awt/Button.java b/jdk/src/share/classes/java/awt/Button.java index 08e569d446a..cc01947a9f1 100644 --- a/jdk/src/share/classes/java/awt/Button.java +++ b/jdk/src/share/classes/java/awt/Button.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1995, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1995, 2014, Oracle and/or its affiliates. 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 @@ -238,6 +238,8 @@ public class Button extends Component implements Accessible { * Returns the command name of the action event fired by this button. * If the command name is null (default) then this method * returns the label of the button. + * + * @return the action command name (or label) for this button */ public String getActionCommand() { return (actionCommand == null? label : actionCommand); diff --git a/jdk/src/share/classes/java/awt/Checkbox.java b/jdk/src/share/classes/java/awt/Checkbox.java index 8e8b5dd226a..021b2fcebaa 100644 --- a/jdk/src/share/classes/java/awt/Checkbox.java +++ b/jdk/src/share/classes/java/awt/Checkbox.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1995, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1995, 2014, Oracle and/or its affiliates. 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 @@ -713,6 +713,9 @@ public class Checkbox extends Component implements ItemSelectable, Accessible { */ private static final long serialVersionUID = 7881579233144754107L; + /** + * Constructor for {@code AccessibleAWTCheckbox} + */ public AccessibleAWTCheckbox() { super(); Checkbox.this.addItemListener(this); diff --git a/jdk/src/share/classes/java/awt/CheckboxGroup.java b/jdk/src/share/classes/java/awt/CheckboxGroup.java index a34c337b712..15e91c4d2a0 100644 --- a/jdk/src/share/classes/java/awt/CheckboxGroup.java +++ b/jdk/src/share/classes/java/awt/CheckboxGroup.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1995, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1995, 2014, Oracle and/or its affiliates. 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 @@ -91,6 +91,10 @@ public class CheckboxGroup implements java.io.Serializable { } /** + * Returns the current choice from this check box group + * or {@code null} if none of checkboxes are selected. + * + * @return the selected checkbox * @deprecated As of JDK version 1.1, * replaced by getSelectedCheckbox(). */ @@ -120,6 +124,11 @@ public class CheckboxGroup implements java.io.Serializable { } /** + * Sets the currently selected check box in this group + * to be the specified check box and unsets all others. + * + * @param box the {@code Checkbox} to set as the + * current selection. * @deprecated As of JDK version 1.1, * replaced by setSelectedCheckbox(Checkbox). */ diff --git a/jdk/src/share/classes/java/awt/Choice.java b/jdk/src/share/classes/java/awt/Choice.java index 1d79dc71831..a6f20718321 100644 --- a/jdk/src/share/classes/java/awt/Choice.java +++ b/jdk/src/share/classes/java/awt/Choice.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1995, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1995, 2014, Oracle and/or its affiliates. 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 @@ -156,6 +156,7 @@ public class Choice extends Component implements ItemSelectable, Accessible { /** * Returns the number of items in this Choice menu. + * * @return the number of items in this Choice menu * @see #getItem * @since 1.1 @@ -165,6 +166,9 @@ public class Choice extends Component implements ItemSelectable, Accessible { } /** + * Returns the number of items in this {@code Choice} menu. + * + * @return the number of items in this {@code Choice} menu * @deprecated As of JDK version 1.1, * replaced by getItemCount(). */ @@ -176,8 +180,10 @@ public class Choice extends Component implements ItemSelectable, Accessible { /** * Gets the string at the specified index in this * Choice menu. - * @param index the index at which to begin - * @see #getItemCount + * + * @param index the index at which to begin + * @return the item at the specified index + * @see #getItemCount */ public String getItem(int index) { return getItemImpl(index); @@ -759,6 +765,9 @@ public class Choice extends Component implements ItemSelectable, Accessible { */ private static final long serialVersionUID = 7175603582428509322L; + /** + * Constructor for {@code AccessibleAWTChoice} + */ public AccessibleAWTChoice() { super(); } diff --git a/jdk/src/share/classes/java/awt/Component.java b/jdk/src/share/classes/java/awt/Component.java index 8e328a5e586..b062cc718b7 100644 --- a/jdk/src/share/classes/java/awt/Component.java +++ b/jdk/src/share/classes/java/awt/Component.java @@ -1075,6 +1075,7 @@ public abstract class Component implements ImageObserver, MenuContainer, * @deprecated As of JDK version 1.1, * programs should not directly manipulate peers; * replaced by boolean isDisplayable(). + * @return the peer for this component */ @Deprecated public ComponentPeer getPeer() { @@ -1132,6 +1133,8 @@ public abstract class Component implements ImageObserver, MenuContainer, /** * Gets the DropTarget associated with this * Component. + * + * @return the drop target */ public synchronized DropTarget getDropTarget() { return dropTarget; } @@ -1498,6 +1501,11 @@ public abstract class Component implements ImageObserver, MenuContainer, } /** + * Enables or disables this component. + * + * @param b {@code true} to enable this component; + * otherwise {@code false} + * * @deprecated As of JDK version 1.1, * replaced by setEnabled(boolean). */ @@ -1656,6 +1664,11 @@ public abstract class Component implements ImageObserver, MenuContainer, } /** + * Makes this component visible or invisible. + * + * @param b {@code true} to make this component visible; + * otherwise {@code false} + * * @deprecated As of JDK version 1.1, * replaced by setVisible(boolean). */ @@ -2068,6 +2081,9 @@ public abstract class Component implements ImageObserver, MenuContainer, /** + * Returns the location of this component's top left corner. + * + * @return the location of this component's top left corner * @deprecated As of JDK version 1.1, * replaced by getLocation(). */ @@ -2102,6 +2118,13 @@ public abstract class Component implements ImageObserver, MenuContainer, } /** + * Moves this component to a new location. + * + * @param x the x-coordinate of the new location's + * top-left corner in the parent's coordinate space + * @param y the y-coordinate of the new location's + * top-left corner in the parent's coordinate space + * * @deprecated As of JDK version 1.1, * replaced by setLocation(int, int). */ @@ -2150,6 +2173,11 @@ public abstract class Component implements ImageObserver, MenuContainer, } /** + * Returns the size of this component in the form of a + * {@code Dimension} object. + * + * @return the {@code Dimension} object that indicates the + * size of this component * @deprecated As of JDK version 1.1, * replaced by getSize(). */ @@ -2177,6 +2205,10 @@ public abstract class Component implements ImageObserver, MenuContainer, } /** + * Resizes this component. + * + * @param width the new width of the component + * @param height the new height of the component * @deprecated As of JDK version 1.1, * replaced by setSize(int, int). */ @@ -2208,6 +2240,10 @@ public abstract class Component implements ImageObserver, MenuContainer, } /** + * Resizes this component so that it has width {@code d.width} + * and height {@code d.height}. + * + * @param d the new size of this component * @deprecated As of JDK version 1.1, * replaced by setSize(Dimension). */ @@ -2231,6 +2267,9 @@ public abstract class Component implements ImageObserver, MenuContainer, } /** + * Returns the bounding rectangle of this component. + * + * @return the bounding rectangle for this component * @deprecated As of JDK version 1.1, * replaced by getBounds(). */ @@ -2265,6 +2304,13 @@ public abstract class Component implements ImageObserver, MenuContainer, } /** + * Reshapes the bounding rectangle for this component. + * + * @param x the x coordinate of the upper left corner of the rectangle + * @param y the y coordinate of the upper left corner of the rectangle + * @param width the width of the rectangle + * @param height the height of the rectangle + * * @deprecated As of JDK version 1.1, * replaced by setBounds(int, int, int, int). */ @@ -2631,6 +2677,9 @@ public abstract class Component implements ImageObserver, MenuContainer, /** + * Returns the component's preferred size. + * + * @return the component's preferred size * @deprecated As of JDK version 1.1, * replaced by getPreferredSize(). */ @@ -2701,6 +2750,9 @@ public abstract class Component implements ImageObserver, MenuContainer, } /** + * Returns the minimum size of this component. + * + * @return the minimum size of this component * @deprecated As of JDK version 1.1, * replaced by getMinimumSize(). */ @@ -2781,6 +2833,8 @@ public abstract class Component implements ImageObserver, MenuContainer, * components. The value should be a number between 0 and 1 * where 0 represents alignment along the origin, 1 is aligned * the furthest away from the origin, 0.5 is centered, etc. + * + * @return the horizontal alignment of this component */ public float getAlignmentX() { return CENTER_ALIGNMENT; @@ -2792,6 +2846,8 @@ public abstract class Component implements ImageObserver, MenuContainer, * components. The value should be a number between 0 and 1 * where 0 represents alignment along the origin, 1 is aligned * the furthest away from the origin, 0.5 is centered, etc. + * + * @return the vertical alignment of this component */ public float getAlignmentY() { return CENTER_ALIGNMENT; @@ -3157,8 +3213,10 @@ public abstract class Component implements ImageObserver, MenuContainer, * not have a cursor set, the cursor of its parent is returned. * If no cursor is set in the entire hierarchy, * Cursor.DEFAULT_CURSOR is returned. + * + * @return the cursor for this component * @see #setCursor - * @since 1.1 + * @since 1.1 */ public Cursor getCursor() { return getCursor_NoClientCode(); @@ -3942,6 +4000,7 @@ public abstract class Component implements ImageObserver, MenuContainer, * a lost state. */ protected boolean validatedContents; // = false + /** * Size of the back buffers. (Note: these fields were added in 6.0 * but kept package-private to avoid exposing them in the spec. @@ -3949,7 +4008,15 @@ public abstract class Component implements ImageObserver, MenuContainer, * protected when they were introduced in 1.4, but now we just have * to live with that decision.) */ + + /** + * The width of the back buffers + */ int width; + + /** + * The height of the back buffers + */ int height; /** @@ -4304,6 +4371,8 @@ public abstract class Component implements ImageObserver, MenuContainer, /** * Creates the back buffers + * + * @param numBuffers the number of buffers to create */ protected void createBackBuffers(int numBuffers) { if (numBuffers == 0) { @@ -4593,6 +4662,9 @@ public abstract class Component implements ImageObserver, MenuContainer, * better performance is desired, or if page-flipping is used as the * buffer strategy. * + * @param ignoreRepaint {@code true} if the paint messages from the OS + * should be ignored; otherwise {@code false} + * * @since 1.4 * @see #getIgnoreRepaint * @see Canvas#createBufferStrategy @@ -4619,8 +4691,11 @@ public abstract class Component implements ImageObserver, MenuContainer, * Checks whether this component "contains" the specified point, * where x and y are defined to be * relative to the coordinate system of this component. + * * @param x the x coordinate of the point * @param y the y coordinate of the point + * @return {@code true} if the point is within the component; + * otherwise {@code false} * @see #getComponentAt(int, int) * @since 1.1 */ @@ -4629,6 +4704,12 @@ public abstract class Component implements ImageObserver, MenuContainer, } /** + * Checks whether the point is inside of this component. + * + * @param x the x coordinate of the point + * @param y the y coordinate of the point + * @return {@code true} if the point is within the component; + * otherwise {@code false} * @deprecated As of JDK version 1.1, * replaced by contains(int, int). */ @@ -4641,7 +4722,10 @@ public abstract class Component implements ImageObserver, MenuContainer, * Checks whether this component "contains" the specified point, * where the point's x and y coordinates are defined * to be relative to the coordinate system of this component. + * * @param p the point + * @return {@code true} if the point is within the component; + * otherwise {@code false} * @throws NullPointerException if {@code p} is {@code null} * @see #getComponentAt(Point) * @since 1.1 @@ -4676,6 +4760,13 @@ public abstract class Component implements ImageObserver, MenuContainer, } /** + * Returns the component occupying the position specified (this component, + * or immediate child component, or null if neither + * of the first two occupies the location). + * + * @param x the x coordinate to search for components at + * @param y the y coordinate to search for components at + * @return the component at the specified location or {@code null} * @deprecated As of JDK version 1.1, * replaced by getComponentAt(int, int). */ @@ -4687,15 +4778,17 @@ public abstract class Component implements ImageObserver, MenuContainer, /** * Returns the component or subcomponent that contains the * specified point. - * @param p the point - * @see java.awt.Component#contains - * @since 1.1 + * @param p the point + * @return the component at the specified location or {@code null} + * @see java.awt.Component#contains + * @since 1.1 */ public Component getComponentAt(Point p) { return getComponentAt(p.x, p.y); } /** + * @param e the event to deliver * @deprecated As of JDK version 1.1, * replaced by dispatchEvent(AWTEvent e). */ @@ -6746,6 +6839,8 @@ public abstract class Component implements ImageObserver, MenuContainer, } /** + * @param evt the event to handle + * @return {@code true} if the event was handled, {@code false} otherwise * @deprecated As of JDK version 1.1 * replaced by processEvent(AWTEvent). */ @@ -6789,6 +6884,10 @@ public abstract class Component implements ImageObserver, MenuContainer, } /** + * @param evt the event to handle + * @param x the x coordinate + * @param y the y coordinate + * @return {@code false} * @deprecated As of JDK version 1.1, * replaced by processMouseEvent(MouseEvent). */ @@ -6798,6 +6897,10 @@ public abstract class Component implements ImageObserver, MenuContainer, } /** + * @param evt the event to handle + * @param x the x coordinate + * @param y the y coordinate + * @return {@code false} * @deprecated As of JDK version 1.1, * replaced by processMouseMotionEvent(MouseEvent). */ @@ -6807,6 +6910,10 @@ public abstract class Component implements ImageObserver, MenuContainer, } /** + * @param evt the event to handle + * @param x the x coordinate + * @param y the y coordinate + * @return {@code false} * @deprecated As of JDK version 1.1, * replaced by processMouseEvent(MouseEvent). */ @@ -6816,6 +6923,10 @@ public abstract class Component implements ImageObserver, MenuContainer, } /** + * @param evt the event to handle + * @param x the x coordinate + * @param y the y coordinate + * @return {@code false} * @deprecated As of JDK version 1.1, * replaced by processMouseMotionEvent(MouseEvent). */ @@ -6825,6 +6936,10 @@ public abstract class Component implements ImageObserver, MenuContainer, } /** + * @param evt the event to handle + * @param x the x coordinate + * @param y the y coordinate + * @return {@code false} * @deprecated As of JDK version 1.1, * replaced by processMouseEvent(MouseEvent). */ @@ -6834,6 +6949,10 @@ public abstract class Component implements ImageObserver, MenuContainer, } /** + * @param evt the event to handle + * @param x the x coordinate + * @param y the y coordinate + * @return {@code false} * @deprecated As of JDK version 1.1, * replaced by processMouseEvent(MouseEvent). */ @@ -6843,6 +6962,9 @@ public abstract class Component implements ImageObserver, MenuContainer, } /** + * @param evt the event to handle + * @param key the key pressed + * @return {@code false} * @deprecated As of JDK version 1.1, * replaced by processKeyEvent(KeyEvent). */ @@ -6852,6 +6974,9 @@ public abstract class Component implements ImageObserver, MenuContainer, } /** + * @param evt the event to handle + * @param key the key pressed + * @return {@code false} * @deprecated As of JDK version 1.1, * replaced by processKeyEvent(KeyEvent). */ @@ -6861,6 +6986,9 @@ public abstract class Component implements ImageObserver, MenuContainer, } /** + * @param evt the event to handle + * @param what the object acted on + * @return {@code false} * @deprecated As of JDK version 1.1, * should register this component as ActionListener on component * which fires action events. @@ -7070,6 +7198,9 @@ public abstract class Component implements ImageObserver, MenuContainer, } /** + * @param evt the event to handle + * @param what the object focused + * @return {@code false} * @deprecated As of JDK version 1.1, * replaced by processFocusEvent(FocusEvent). */ @@ -7079,6 +7210,9 @@ public abstract class Component implements ImageObserver, MenuContainer, } /** + * @param evt the event to handle + * @param what the object focused + * @return {@code false} * @deprecated As of JDK version 1.1, * replaced by processFocusEvent(FocusEvent). */ @@ -8390,6 +8524,7 @@ public abstract class Component implements ImageObserver, MenuContainer, * Returns an array of all the listeners which have been associated * with the named property. * + * @param propertyName the property name * @return all of the PropertyChangeListeners associated with * the named property; if no such listeners have been added or * if propertyName is null, an empty @@ -8400,8 +8535,7 @@ public abstract class Component implements ImageObserver, MenuContainer, * @see #getPropertyChangeListeners * @since 1.4 */ - public PropertyChangeListener[] getPropertyChangeListeners( - String propertyName) { + public PropertyChangeListener[] getPropertyChangeListeners(String propertyName) { synchronized (getObjectLock()) { if (changeSupport == null) { return new PropertyChangeListener[0]; @@ -8879,6 +9013,7 @@ public abstract class Component implements ImageObserver, MenuContainer, * This method changes layout-related information, and therefore, * invalidates the component hierarchy. * + * @param o the orientation to be set * * @see ComponentOrientation * @see #invalidate @@ -8906,6 +9041,7 @@ public abstract class Component implements ImageObserver, MenuContainer, * subclasses that wish to respect orientation should call this method to * get the component's orientation before performing layout or drawing. * + * @return the orientation to order the elements or text * @see ComponentOrientation * * @author Laura Werner, IBM @@ -9063,7 +9199,16 @@ public abstract class Component implements ImageObserver, MenuContainer, */ private volatile transient int propertyListenersCount = 0; + /** + * A component listener to track show/hide/resize events + * and convert them to PropertyChange events. + */ protected ComponentListener accessibleAWTComponentHandler = null; + + /** + * A listener to track focus events + * and convert them to PropertyChange events. + */ protected FocusListener accessibleAWTFocusHandler = null; /** diff --git a/jdk/src/share/classes/java/awt/ComponentOrientation.java b/jdk/src/share/classes/java/awt/ComponentOrientation.java index 8655aafa322..226b004a273 100644 --- a/jdk/src/share/classes/java/awt/ComponentOrientation.java +++ b/jdk/src/share/classes/java/awt/ComponentOrientation.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1998, 2006, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1998, 2014, Oracle and/or its affiliates. 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 @@ -126,6 +126,8 @@ public final class ComponentOrientation implements java.io.Serializable * Are lines horizontal? * This will return true for horizontal, left-to-right writing * systems such as Roman. + * + * @return {@code true} if this orientation has horizontal lines */ public boolean isHorizontal() { return (orientation & HORIZ_BIT) != 0; @@ -136,6 +138,8 @@ public final class ComponentOrientation implements java.io.Serializable * Vertical Lines: Do lines run left-to-right?
* This will return true for horizontal, left-to-right writing * systems such as Roman. + * + * @return {@code true} if this orientation is left-to-right */ public boolean isLeftToRight() { return (orientation & LTR_BIT) != 0; @@ -143,7 +147,9 @@ public final class ComponentOrientation implements java.io.Serializable /** * Returns the orientation that is appropriate for the given locale. + * * @param locale the specified locale + * @return the orientation for the locale */ public static ComponentOrientation getOrientation(Locale locale) { // A more flexible implementation would consult a ResourceBundle @@ -171,6 +177,8 @@ public final class ComponentOrientation implements java.io.Serializable *
  • Return the default locale's orientation. * * + * @param bdl the bundle to use + * @return the orientation * @deprecated As of J2SE 1.4, use {@link #getOrientation(java.util.Locale)}. */ @Deprecated diff --git a/jdk/src/share/classes/java/awt/Container.java b/jdk/src/share/classes/java/awt/Container.java index a352bab43ef..95997f4f900 100644 --- a/jdk/src/share/classes/java/awt/Container.java +++ b/jdk/src/share/classes/java/awt/Container.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1995, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1995, 2014, Oracle and/or its affiliates. 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 @@ -310,6 +310,9 @@ public class Container extends Component { } /** + * Returns the number of components in this container. + * + * @return the number of components in this container * @deprecated As of JDK version 1.1, * replaced by getComponentCount(). */ @@ -391,8 +394,11 @@ public class Container extends Component { } /** + * Returns the insets for this container. + * * @deprecated As of JDK version 1.1, * replaced by getInsets(). + * @return the insets for this container */ @Deprecated public Insets insets() { @@ -438,6 +444,9 @@ public class Container extends Component { * displayed, the hierarchy must be validated thereafter in order to * display the added component. * + * @param name the name of the component to be added + * @param comp the component to be added + * @return the component added * @exception NullPointerException if {@code comp} is {@code null} * @see #add(Component, Object) * @see #invalidate @@ -1471,8 +1480,10 @@ public class Container extends Component { /** * Gets the layout manager for this container. + * * @see #doLayout * @see #setLayout + * @return the current layout manager for this container */ public LayoutManager getLayout() { return layoutMgr; @@ -3854,6 +3865,10 @@ public class Container extends Component { */ private volatile transient int propertyListenersCount = 0; + /** + * The handler to fire {@code PropertyChange} + * when children are added or removed + */ protected ContainerListener accessibleContainerHandler = null; /** diff --git a/jdk/src/share/classes/java/awt/Cursor.java b/jdk/src/share/classes/java/awt/Cursor.java index 794c7c9b242..1468e162134 100644 --- a/jdk/src/share/classes/java/awt/Cursor.java +++ b/jdk/src/share/classes/java/awt/Cursor.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1996, 2014, Oracle and/or its affiliates. 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 @@ -294,6 +294,7 @@ public class Cursor implements java.io.Serializable { * @return the system specific custom cursor named * @exception HeadlessException if * GraphicsEnvironment.isHeadless returns true + * @exception AWTException in case of erroneous retrieving of the cursor */ static public Cursor getSystemCustomCursor(final String name) throws AWTException, HeadlessException { @@ -378,6 +379,8 @@ public class Cursor implements java.io.Serializable { /** * Return the system default cursor. + * + * @return the default cursor */ static public Cursor getDefaultCursor() { return getPredefinedCursor(Cursor.DEFAULT_CURSOR); @@ -416,6 +419,8 @@ public class Cursor implements java.io.Serializable { /** * Returns the type for this cursor. + * + * @return the cursor type */ public int getType() { return type; diff --git a/jdk/src/share/classes/java/awt/DisplayMode.java b/jdk/src/share/classes/java/awt/DisplayMode.java index 71a5d7e8122..41564300615 100644 --- a/jdk/src/share/classes/java/awt/DisplayMode.java +++ b/jdk/src/share/classes/java/awt/DisplayMode.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2000, 2014, Oracle and/or its affiliates. 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 @@ -125,6 +125,8 @@ public final class DisplayMode { /** * Returns whether the two display modes are equal. + * + * @param dm the display mode to compare to * @return whether the two display modes are equal */ public boolean equals(DisplayMode dm) { diff --git a/jdk/src/share/classes/java/awt/EventQueue.java b/jdk/src/share/classes/java/awt/EventQueue.java index 87bbace3ac8..a89311352ab 100644 --- a/jdk/src/share/classes/java/awt/EventQueue.java +++ b/jdk/src/share/classes/java/awt/EventQueue.java @@ -222,6 +222,9 @@ public class EventQueue { }); } + /** + * Initializes a new instance of {@code EventQueue}. + */ public EventQueue() { for (int i = 0; i < NUM_PRIORITIES; i++) { queues[i] = new Queue(); diff --git a/jdk/src/share/classes/java/awt/Frame.java b/jdk/src/share/classes/java/awt/Frame.java index df3fcda4773..c6ce4814078 100644 --- a/jdk/src/share/classes/java/awt/Frame.java +++ b/jdk/src/share/classes/java/awt/Frame.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1995, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1995, 2014, Oracle and/or its affiliates. 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 @@ -1089,6 +1089,9 @@ public class Frame extends Window implements MenuContainer { } /** + * Sets the cursor for this frame to the specified type. + * + * @param cursorType the cursor type * @deprecated As of JDK version 1.1, * replaced by Component.setCursor(Cursor). */ @@ -1103,6 +1106,7 @@ public class Frame extends Window implements MenuContainer { /** * @deprecated As of JDK version 1.1, * replaced by Component.getCursor(). + * @return the cursor type for this frame */ @Deprecated public int getCursorType() { @@ -1124,6 +1128,8 @@ public class Frame extends Window implements MenuContainer { * ownerless {@code Dialog}s (introduced in release 1.6), use {@link * Window#getOwnerlessWindows Window.getOwnerlessWindows}. * + * @return the array of all {@code Frame}s created by this application + * * @see Window#getWindows() * @see Window#getOwnerlessWindows * diff --git a/jdk/src/share/classes/java/awt/GraphicsEnvironment.java b/jdk/src/share/classes/java/awt/GraphicsEnvironment.java index e9e9080dba6..2d6436cc00d 100644 --- a/jdk/src/share/classes/java/awt/GraphicsEnvironment.java +++ b/jdk/src/share/classes/java/awt/GraphicsEnvironment.java @@ -357,6 +357,8 @@ public abstract class GraphicsEnvironment { *

    Notice that an application can supersede the registration * of an earlier created font with a new one. * + * + * @param font the font to be registered * @return true if the font is successfully * registered in this GraphicsEnvironment. * @throws NullPointerException if font is null diff --git a/jdk/src/share/classes/java/awt/GridBagLayout.java b/jdk/src/share/classes/java/awt/GridBagLayout.java index 0b2c32ba2b5..981c993751a 100644 --- a/jdk/src/share/classes/java/awt/GridBagLayout.java +++ b/jdk/src/share/classes/java/awt/GridBagLayout.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1995, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1995, 2014, Oracle and/or its affiliates. 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 @@ -981,9 +981,15 @@ java.io.Serializable { * This method is obsolete and supplied for backwards * compatibility only; new code should call {@link * #getLayoutInfo(java.awt.Container, int) getLayoutInfo} instead. - * This method is the same as getLayoutInfo; - * refer to getLayoutInfo for details on parameters - * and return value. + * + * Fills in an instance of {@code GridBagLayoutInfo} for the + * current set of managed children. This method is the same + * as {@code getLayoutInfo}; refer to {@code getLayoutInfo} + * description for details. + * + * @param parent the layout container + * @param sizeflag either {@code PREFERREDSIZE} or {@code MINSIZE} + * @return the {@code GridBagLayoutInfo} for the set of children */ protected GridBagLayoutInfo GetLayoutInfo(Container parent, int sizeflag) { synchronized (parent.getTreeLock()) { @@ -1611,13 +1617,17 @@ java.io.Serializable { } /** + * Adjusts the x, y, width, and height fields to the correct + * values depending on the constraint geometry and pads. + *

    * This method is obsolete and supplied for backwards * compatibility only; new code should call {@link * #adjustForGravity(java.awt.GridBagConstraints, java.awt.Rectangle) * adjustForGravity} instead. - * This method is the same as adjustForGravity; - * refer to adjustForGravity for details - * on parameters. + * This method is the same as adjustForGravity + * + * @param constraints the constraints to be applied + * @param r the {@code Rectangle} to be adjusted */ protected void AdjustForGravity(GridBagConstraints constraints, Rectangle r) { @@ -1995,9 +2005,12 @@ java.io.Serializable { * This method is obsolete and supplied for backwards * compatibility only; new code should call {@link * #getMinSize(java.awt.Container, GridBagLayoutInfo) getMinSize} instead. - * This method is the same as getMinSize; - * refer to getMinSize for details on parameters - * and return value. + * This method is the same as getMinSize + * + * @param parent the layout container + * @param info the layout info for this parent + * @return a Dimension object containing the + * minimum size */ protected Dimension GetMinSize(Container parent, GridBagLayoutInfo info) { Dimension d = new Dimension(); @@ -2035,9 +2048,9 @@ java.io.Serializable { * This method is obsolete and supplied for backwards * compatibility only; new code should call {@link * #arrangeGrid(Container) arrangeGrid} instead. - * This method is the same as arrangeGrid; - * refer to arrangeGrid for details on the - * parameter. + * This method is the same as arrangeGrid + * + * @param parent the layout container */ protected void ArrangeGrid(Container parent) { Component comp; diff --git a/jdk/src/share/classes/java/awt/HeadlessException.java b/jdk/src/share/classes/java/awt/HeadlessException.java index db53a351c6d..5809ffd9faf 100644 --- a/jdk/src/share/classes/java/awt/HeadlessException.java +++ b/jdk/src/share/classes/java/awt/HeadlessException.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2000, 2004, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2000, 2014, Oracle and/or its affiliates. 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 @@ -38,10 +38,24 @@ public class HeadlessException extends UnsupportedOperationException { * JDK 1.4 serialVersionUID */ private static final long serialVersionUID = 167183644944358563L; + + /** + * Constructs new {@code HeadlessException} + */ public HeadlessException() {} + + /** + * Create a new instance with the specified detailed error message. + * + * @param msg the error message + */ public HeadlessException(String msg) { super(msg); } + + /** + * {@inheritDoc} + */ public String getMessage() { String superMessage = super.getMessage(); String headlessMessage = GraphicsEnvironment.getHeadlessMessage(); diff --git a/jdk/src/share/classes/java/awt/ItemSelectable.java b/jdk/src/share/classes/java/awt/ItemSelectable.java index d19afb3ab0d..e11b70ef48f 100644 --- a/jdk/src/share/classes/java/awt/ItemSelectable.java +++ b/jdk/src/share/classes/java/awt/ItemSelectable.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1996, 2000, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1996, 2014, Oracle and/or its affiliates. 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,8 @@ public interface ItemSelectable { /** * Returns the selected items or null if no * items are selected. + * + * @return the list of selected objects, or {@code null} */ public Object[] getSelectedObjects(); diff --git a/jdk/src/share/classes/java/awt/KeyboardFocusManager.java b/jdk/src/share/classes/java/awt/KeyboardFocusManager.java index 8758a2b50e3..57a8f733ce7 100644 --- a/jdk/src/share/classes/java/awt/KeyboardFocusManager.java +++ b/jdk/src/share/classes/java/awt/KeyboardFocusManager.java @@ -1459,6 +1459,7 @@ public abstract class KeyboardFocusManager * Returns an array of all the PropertyChangeListeners * associated with the named property. * + * @param propertyName the property name * @return all of the PropertyChangeListeners associated with * the named property or an empty array if no such listeners have * been added. @@ -1628,6 +1629,7 @@ public abstract class KeyboardFocusManager * Returns an array of all the VetoableChangeListeners * associated with the named property. * + * @param propertyName the property name * @return all of the VetoableChangeListeners associated with * the named property or an empty array if no such listeners have * been added. diff --git a/jdk/src/share/classes/java/awt/Label.java b/jdk/src/share/classes/java/awt/Label.java index 20ccdcd4c86..c8aab9569ff 100644 --- a/jdk/src/share/classes/java/awt/Label.java +++ b/jdk/src/share/classes/java/awt/Label.java @@ -193,7 +193,8 @@ public class Label extends Component implements Accessible { * Gets the current alignment of this label. Possible values are * Label.LEFT, Label.RIGHT, and * Label.CENTER. - * @see java.awt.Label#setAlignment + * @return the alignment of this label + * @see java.awt.Label#setAlignment */ public int getAlignment() { return alignment; @@ -321,6 +322,9 @@ public class Label extends Component implements Accessible { */ private static final long serialVersionUID = -3568967560160480438L; + /** + * Constructor for the accessible label. + */ public AccessibleAWTLabel() { super(); } diff --git a/jdk/src/share/classes/java/awt/LayoutManager.java b/jdk/src/share/classes/java/awt/LayoutManager.java index 5a00db263e6..d7abfbb1c29 100644 --- a/jdk/src/share/classes/java/awt/LayoutManager.java +++ b/jdk/src/share/classes/java/awt/LayoutManager.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1995, 2005, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1995, 2014, Oracle and/or its affiliates. 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 @@ -61,7 +61,9 @@ public interface LayoutManager { /** * Calculates the preferred size dimensions for the specified * container, given the components it contains. - * @param parent the container to be laid out + * + * @param parent the container to be laid out + * @return the preferred dimension for the container * * @see #minimumLayoutSize */ @@ -70,7 +72,10 @@ public interface LayoutManager { /** * Calculates the minimum size dimensions for the specified * container, given the components it contains. - * @param parent the component to be laid out + * + * @param parent the component to be laid out + * @return the minimum dimension for the container + * * @see #preferredLayoutSize */ Dimension minimumLayoutSize(Container parent); diff --git a/jdk/src/share/classes/java/awt/LayoutManager2.java b/jdk/src/share/classes/java/awt/LayoutManager2.java index ae6516e17b8..347295052e4 100644 --- a/jdk/src/share/classes/java/awt/LayoutManager2.java +++ b/jdk/src/share/classes/java/awt/LayoutManager2.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1996, 2001, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1996, 2014, Oracle and/or its affiliates. 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,8 +55,11 @@ public interface LayoutManager2 extends LayoutManager { /** * Calculates the maximum size dimensions for the specified container, * given the components it contains. + * * @see java.awt.Component#getMaximumSize * @see LayoutManager + * @param target the target container + * @return the maximum size of the container */ public Dimension maximumLayoutSize(Container target); @@ -66,6 +69,9 @@ public interface LayoutManager2 extends LayoutManager { * components. The value should be a number between 0 and 1 * where 0 represents alignment along the origin, 1 is aligned * the furthest away from the origin, 0.5 is centered, etc. + * + * @param target the target container + * @return the x-axis alignment preference */ public float getLayoutAlignmentX(Container target); @@ -75,12 +81,16 @@ public interface LayoutManager2 extends LayoutManager { * components. The value should be a number between 0 and 1 * where 0 represents alignment along the origin, 1 is aligned * the furthest away from the origin, 0.5 is centered, etc. + * + * @param target the target container + * @return the y-axis alignment preference */ public float getLayoutAlignmentY(Container target); /** * Invalidates the layout, indicating that if the layout manager * has cached information it should be discarded. + * @param target the target container */ public void invalidateLayout(Container target); diff --git a/jdk/src/share/classes/java/awt/List.java b/jdk/src/share/classes/java/awt/List.java index df638c26724..ede6f643157 100644 --- a/jdk/src/share/classes/java/awt/List.java +++ b/jdk/src/share/classes/java/awt/List.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1995, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1995, 2014, Oracle and/or its affiliates. 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 @@ -282,6 +282,9 @@ public class List extends Component implements ItemSelectable, Accessible { } /** + * Returns the number of items in the list. + * + * @return the number of items in the list * @deprecated As of JDK version 1.1, * replaced by getItemCount(). */ @@ -333,7 +336,10 @@ public class List extends Component implements ItemSelectable, Accessible { } /** - * @deprecated replaced by add(String). + * Adds the specified item to the end of the list. + * + * @param item the item to be added + * @deprecated replaced by add(String). */ @Deprecated public void addItem(String item) { @@ -358,7 +364,12 @@ public class List extends Component implements ItemSelectable, Accessible { } /** - * @deprecated replaced by add(String, int). + * Adds the specified item to the the list + * at the position indicated by the index. + * + * @param item the item to be added + * @param index the position at which to add the item + * @deprecated replaced by add(String, int). */ @Deprecated public synchronized void addItem(String item, int index) { @@ -455,8 +466,11 @@ public class List extends Component implements ItemSelectable, Accessible { } /** - * @deprecated replaced by remove(String) - * and remove(int). + * Removes the item at the specified position. + * + * @param position the index of the item to delete + * @deprecated replaced by remove(String) + * and remove(int). */ @Deprecated public void delItem(int position) { @@ -646,6 +660,10 @@ public class List extends Component implements ItemSelectable, Accessible { } /** + * Determines if the specified item in the list is selected. + * + * @param index specifies the item to be checked + * @return {@code true} if the item is selected; otherwise {@code false} * @deprecated As of JDK version 1.1, * replaced by isIndexSelected(int). */ @@ -672,6 +690,7 @@ public class List extends Component implements ItemSelectable, Accessible { /** * Determines whether this list allows multiple selections. + * * @return true if this list allows multiple * selections; otherwise, false * @see #setMultipleMode @@ -682,6 +701,10 @@ public class List extends Component implements ItemSelectable, Accessible { } /** + * Determines whether this list allows multiple selections. + * + * @return {@code true} if this list allows multiple + * selections; otherwise {@code false} * @deprecated As of JDK version 1.1, * replaced by isMultipleMode(). */ @@ -709,6 +732,9 @@ public class List extends Component implements ItemSelectable, Accessible { } /** + * Enables or disables multiple selection mode for this list. + * + * @param b {@code true} to enable multiple mode, {@code false} otherwise * @deprecated As of JDK version 1.1, * replaced by setMultipleMode(boolean). */ @@ -760,6 +786,11 @@ public class List extends Component implements ItemSelectable, Accessible { } /** + * Returns the preferred size of this component + * assuming it has the specified number of rows. + * + * @param rows the number of rows + * @return the preferred dimensions for displaying this list * @deprecated As of JDK version 1.1, * replaced by getPreferredSize(int). */ @@ -810,6 +841,11 @@ public class List extends Component implements ItemSelectable, Accessible { } /** + * Returns the minimum dimensions for the list + * with the specified number of rows. + * + * @param rows the number of rows in the list + * @return the minimum dimensions for displaying this list * @deprecated As of JDK version 1.1, * replaced by getMinimumSize(int). */ @@ -1146,6 +1182,10 @@ public class List extends Component implements ItemSelectable, Accessible { } /** + * Deletes the list items in the specified index range. + * + * @param start the beginning index of the range to delete + * @param end the ending index of the range to delete * @deprecated As of JDK version 1.1, * Not for public use in the future. * This method is expected to be retained only as a package @@ -1290,6 +1330,9 @@ public class List extends Component implements ItemSelectable, Accessible { */ private static final long serialVersionUID = 7924617370136012829L; + /** + * Constructs new {@code AccessibleAWTList} + */ public AccessibleAWTList() { super(); List.this.addActionListener(this); @@ -1491,6 +1534,13 @@ public class List extends Component implements ItemSelectable, Accessible { private List parent; private int indexInParent; + /** + * Constructs new {@code AccessibleAWTListChild} with the given + * parent {@code List} and 0-based index of this object in the parent. + * + * @param parent the parent {@code List} + * @param indexInParent the index in the parent + */ public AccessibleAWTListChild(List parent, int indexInParent) { this.parent = parent; this.setAccessibleParent(parent); diff --git a/jdk/src/share/classes/java/awt/MediaTracker.java b/jdk/src/share/classes/java/awt/MediaTracker.java index b8df6320cfa..dd8f9e0825f 100644 --- a/jdk/src/share/classes/java/awt/MediaTracker.java +++ b/jdk/src/share/classes/java/awt/MediaTracker.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1995, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1995, 2014, Oracle and/or its affiliates. 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 @@ -643,9 +643,11 @@ public class MediaTracker implements java.io.Serializable { * image is considered to have finished loading. Use the * statusID, isErrorID, and * isErrorAny methods to check for errors. - * @param id the identifier of the images to check - * @param ms the length of time, in milliseconds, to wait - * for the loading to complete + * @param id the identifier of the images to check + * @param ms the length of time, in milliseconds, to wait + * for the loading to complete + * @return {@code true} if the loading completed in time; + * otherwise {@code false} * @see java.awt.MediaTracker#waitForAll * @see java.awt.MediaTracker#waitForID(int) * @see java.awt.MediaTracker#statusID diff --git a/jdk/src/share/classes/java/awt/Menu.java b/jdk/src/share/classes/java/awt/Menu.java index 177f208be05..3c8154338ac 100644 --- a/jdk/src/share/classes/java/awt/Menu.java +++ b/jdk/src/share/classes/java/awt/Menu.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1995, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1995, 2014, Oracle and/or its affiliates. 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 @@ -213,7 +213,7 @@ public class Menu extends MenuItem implements MenuContainer, Accessible { /** * Get the number of items in this menu. - * @return the number of items in this menu. + * @return the number of items in this menu * @since 1.1 */ public int getItemCount() { @@ -221,6 +221,9 @@ public class Menu extends MenuItem implements MenuContainer, Accessible { } /** + * Returns the number of items in this menu. + * + * @return the number of items in this menu * @deprecated As of JDK version 1.1, * replaced by getItemCount(). */ diff --git a/jdk/src/share/classes/java/awt/MenuBar.java b/jdk/src/share/classes/java/awt/MenuBar.java index 4e48c7c38ce..4fa4723c417 100644 --- a/jdk/src/share/classes/java/awt/MenuBar.java +++ b/jdk/src/share/classes/java/awt/MenuBar.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1995, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1995, 2014, Oracle and/or its affiliates. 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 @@ -279,6 +279,9 @@ public class MenuBar extends MenuComponent implements MenuContainer, Accessible } /** + * Gets the number of menus on the menu bar. + * + * @return the number of menus on the menu bar. * @deprecated As of JDK version 1.1, * replaced by getMenuCount(). */ @@ -338,10 +341,11 @@ public class MenuBar extends MenuComponent implements MenuContainer, Accessible * or null if none of the menu items being managed * by this menu bar is associated with the specified menu * shortcut. - * @param s the specified menu shortcut. - * @see java.awt.MenuItem - * @see java.awt.MenuShortcut - * @since 1.1 + * @param s the specified menu shortcut. + * @return the menu item for the specified shortcut. + * @see java.awt.MenuItem + * @see java.awt.MenuShortcut + * @since 1.1 */ public MenuItem getShortcutMenuItem(MenuShortcut s) { int nmenus = getMenuCount(); diff --git a/jdk/src/share/classes/java/awt/MenuComponent.java b/jdk/src/share/classes/java/awt/MenuComponent.java index 28fb9ab209e..4ea95bf5969 100644 --- a/jdk/src/share/classes/java/awt/MenuComponent.java +++ b/jdk/src/share/classes/java/awt/MenuComponent.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1995, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1995, 2014, Oracle and/or its affiliates. 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 @@ -220,6 +220,7 @@ public abstract class MenuComponent implements java.io.Serializable { /** * @deprecated As of JDK version 1.1, * programs should not directly manipulate peers. + * @return the peer for this component */ @Deprecated public MenuComponentPeer getPeer() { diff --git a/jdk/src/share/classes/java/awt/MenuContainer.java b/jdk/src/share/classes/java/awt/MenuContainer.java index 8b43f992f4f..8ba5e70245b 100644 --- a/jdk/src/share/classes/java/awt/MenuContainer.java +++ b/jdk/src/share/classes/java/awt/MenuContainer.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1995, 2004, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1995, 2014, Oracle and/or its affiliates. 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,10 +31,25 @@ package java.awt; */ public interface MenuContainer { + + /** + * Returns the font in use by this container. + * + * @return the menu font + */ Font getFont(); + + /** + * Removes the specified menu component from the menu. + * + * @param comp the menu component to remove + */ void remove(MenuComponent comp); /** + * Posts an event to the listeners. + * + * @param evt the event to dispatch * @deprecated As of JDK version 1.1 * replaced by dispatchEvent(AWTEvent). */ diff --git a/jdk/src/share/classes/java/awt/MenuItem.java b/jdk/src/share/classes/java/awt/MenuItem.java index a81c1314700..ab797f4dd1a 100644 --- a/jdk/src/share/classes/java/awt/MenuItem.java +++ b/jdk/src/share/classes/java/awt/MenuItem.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1995, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1995, 2014, Oracle and/or its affiliates. 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 @@ -264,6 +264,9 @@ public class MenuItem extends MenuComponent implements Accessible { /** * Checks whether this menu item is enabled. + * + * @return {@code true} if the item is enabled; + * otherwise {@code false} * @see java.awt.MenuItem#setEnabled * @since 1.0 */ @@ -296,6 +299,10 @@ public class MenuItem extends MenuComponent implements Accessible { } /** + * Sets whether or not this menu item can be chosen. + * + * @param b if {@code true}, enables this menu item; + * otherwise disables * @deprecated As of JDK version 1.1, * replaced by setEnabled(boolean). */ @@ -494,8 +501,10 @@ public class MenuItem extends MenuComponent implements Accessible { /** * Gets the command name of the action event that is fired * by this menu item. - * @see java.awt.MenuItem#setActionCommand - * @since 1.1 + * + * @return the action command name + * @see java.awt.MenuItem#setActionCommand + * @since 1.1 */ public String getActionCommand() { return getActionCommandImpl(); diff --git a/jdk/src/share/classes/java/awt/PrintGraphics.java b/jdk/src/share/classes/java/awt/PrintGraphics.java index 91e5173f81f..74c2f84a31e 100644 --- a/jdk/src/share/classes/java/awt/PrintGraphics.java +++ b/jdk/src/share/classes/java/awt/PrintGraphics.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1996, 1997, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1996, 2014, Oracle and/or its affiliates. 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 @@ -35,6 +35,8 @@ public interface PrintGraphics { /** * Returns the PrintJob object from which this PrintGraphics * object originated. + * + * @return the print job for this object */ public PrintJob getPrintJob(); diff --git a/jdk/src/share/classes/java/awt/PrintJob.java b/jdk/src/share/classes/java/awt/PrintJob.java index 996d7653526..fcc6afebf2a 100644 --- a/jdk/src/share/classes/java/awt/PrintJob.java +++ b/jdk/src/share/classes/java/awt/PrintJob.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1996, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1996, 2014, Oracle and/or its affiliates. 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 @@ -42,6 +42,7 @@ public abstract class PrintJob { * object is disposed. This graphics object will also implement * the PrintGraphics interface. * @see PrintGraphics + * @return the graphics context for printing the next page */ public abstract Graphics getGraphics(); @@ -49,6 +50,8 @@ public abstract class PrintJob { * Returns the dimensions of the page in pixels. * The resolution of the page is chosen so that it * is similar to the screen resolution. + * + * @return the page dimension */ public abstract Dimension getPageDimension(); @@ -56,11 +59,16 @@ public abstract class PrintJob { * Returns the resolution of the page in pixels per inch. * Note that this doesn't have to correspond to the physical * resolution of the printer. + * + * @return the page resolution */ public abstract int getPageResolution(); /** * Returns true if the last page will be printed first. + * + * @return {@code true} if the last page will be printed first; + * otherwise {@code false} */ public abstract boolean lastPageFirst(); diff --git a/jdk/src/share/classes/java/awt/Robot.java b/jdk/src/share/classes/java/awt/Robot.java index cc734dd45a2..8de89ee8ed9 100644 --- a/jdk/src/share/classes/java/awt/Robot.java +++ b/jdk/src/share/classes/java/awt/Robot.java @@ -498,6 +498,8 @@ public class Robot { /** * Returns the number of milliseconds this Robot sleeps after generating an event. + * + * @return the delay duration in milliseconds */ public synchronized int getAutoDelay() { return autoDelay; @@ -505,7 +507,10 @@ public class Robot { /** * Sets the number of milliseconds this Robot sleeps after generating an event. - * @throws IllegalArgumentException If ms is not between 0 and 60,000 milliseconds inclusive + * + * @param ms the delay duration in milliseconds + * @throws IllegalArgumentException If {@code ms} + * is not between 0 and 60,000 milliseconds inclusive */ public synchronized void setAutoDelay(int ms) { checkDelayArgument(ms); @@ -523,9 +528,11 @@ public class Robot { * Sleeps for the specified time. * To catch any InterruptedExceptions that occur, * Thread.sleep() may be used instead. - * @param ms time to sleep in milliseconds - * @throws IllegalArgumentException if ms is not between 0 and 60,000 milliseconds inclusive - * @see java.lang.Thread#sleep + * + * @param ms time to sleep in milliseconds + * @throws IllegalArgumentException if {@code ms} + * is not between 0 and 60,000 milliseconds inclusive + * @see java.lang.Thread#sleep */ public synchronized void delay(int ms) { checkDelayArgument(ms); diff --git a/jdk/src/share/classes/java/awt/ScrollPane.java b/jdk/src/share/classes/java/awt/ScrollPane.java index 70ca48f4d74..fb5401d06f6 100644 --- a/jdk/src/share/classes/java/awt/ScrollPane.java +++ b/jdk/src/share/classes/java/awt/ScrollPane.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1996, 2014, Oracle and/or its affiliates. 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 @@ -323,7 +323,9 @@ public class ScrollPane extends Container implements Accessible { * represents the state of the vertical scrollbar. * The declared return type of this method is * Adjustable to maintain backward compatibility. + * * @see java.awt.ScrollPaneAdjustable + * @return the vertical scrollbar state */ public Adjustable getVAdjustable() { return vAdjustable; @@ -334,7 +336,9 @@ public class ScrollPane extends Container implements Accessible { * represents the state of the horizontal scrollbar. * The declared return type of this method is * Adjustable to maintain backward compatibility. + * * @see java.awt.ScrollPaneAdjustable + * @return the horizontal scrollbar state */ public Adjustable getHAdjustable() { return hAdjustable; @@ -657,6 +661,9 @@ public class ScrollPane extends Container implements Accessible { * Indicates whether or not scrolling will take place in response to * the mouse wheel. Wheel scrolling is enabled by default. * + * @return {@code true} if the wheel scrolling enabled; + * otherwise {@code false} + * * @see #setWheelScrollingEnabled(boolean) * @since 1.4 */ diff --git a/jdk/src/share/classes/java/awt/Scrollbar.java b/jdk/src/share/classes/java/awt/Scrollbar.java index bf119ae2779..28c84efb923 100644 --- a/jdk/src/share/classes/java/awt/Scrollbar.java +++ b/jdk/src/share/classes/java/awt/Scrollbar.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1995, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1995, 2014, Oracle and/or its affiliates. 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 @@ -656,6 +656,9 @@ public class Scrollbar extends Component implements Adjustable, Accessible { } /** + * Returns the visible amount of this scroll bar. + * + * @return the visible amount of this scroll bar * @deprecated As of JDK version 1.1, * replaced by getVisibleAmount(). */ @@ -729,6 +732,10 @@ public class Scrollbar extends Component implements Adjustable, Accessible { } /** + * Sets the unit increment for this scroll bar. + * + * @param v the increment value + * * @deprecated As of JDK version 1.1, * replaced by setUnitIncrement(int). */ @@ -768,6 +775,9 @@ public class Scrollbar extends Component implements Adjustable, Accessible { } /** + * Returns the unit increment for this scrollbar. + * + * @return the unit increment for this scrollbar * @deprecated As of JDK version 1.1, * replaced by getUnitIncrement(). */ @@ -797,6 +807,9 @@ public class Scrollbar extends Component implements Adjustable, Accessible { } /** + * Sets the block increment for this scroll bar. + * + * @param v the block increment * @deprecated As of JDK version 1.1, * replaced by setBlockIncrement(). */ @@ -833,6 +846,10 @@ public class Scrollbar extends Component implements Adjustable, Accessible { } /** + * Returns the block increment of this scroll bar. + * + * @return the block increment of this scroll bar + * * @deprecated As of JDK version 1.1, * replaced by getBlockIncrement(). */ diff --git a/jdk/src/share/classes/java/awt/TextArea.java b/jdk/src/share/classes/java/awt/TextArea.java index dd90aa7414e..f29da08b537 100644 --- a/jdk/src/share/classes/java/awt/TextArea.java +++ b/jdk/src/share/classes/java/awt/TextArea.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1995, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1995, 2014, Oracle and/or its affiliates. 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 @@ -314,6 +314,11 @@ public class TextArea extends TextComponent { } /** + * Inserts the specified text at the specified position + * in this text area. + * + * @param str the non-{@code null} text to insert + * @param pos the position at which to insert * @deprecated As of JDK version 1.1, * replaced by insert(String, int). */ @@ -342,6 +347,9 @@ public class TextArea extends TextComponent { } /** + * Appends the given text to the text area's current text. + * + * @param str the text to append * @deprecated As of JDK version 1.1, * replaced by append(String). */ @@ -378,6 +386,15 @@ public class TextArea extends TextComponent { } /** + * Replaces a range of characters between + * the indicated start and end positions + * with the specified replacement text (the text at the end + * position will not be replaced). + * + * @param str the non-{@code null} text to use as + * the replacement + * @param start the start position + * @param end the end position * @deprecated As of JDK version 1.1, * replaced by replaceRange(String, int, int). */ @@ -492,6 +509,12 @@ public class TextArea extends TextComponent { } /** + * Determines the preferred size of the text area with the specified + * number of rows and columns. + * + * @param rows the number of rows + * @param columns the number of columns + * @return the preferred dimensions needed for the text area * @deprecated As of JDK version 1.1, * replaced by getPreferredSize(int, int). */ @@ -544,6 +567,12 @@ public class TextArea extends TextComponent { } /** + * Determines the minimum size of the text area with the specified + * number of rows and columns. + * + * @param rows the number of rows + * @param columns the number of columns + * @return the minimum size for the text area * @deprecated As of JDK version 1.1, * replaced by getMinimumSize(int, int). */ diff --git a/jdk/src/share/classes/java/awt/TextComponent.java b/jdk/src/share/classes/java/awt/TextComponent.java index 104fe02e53b..639438a2a1d 100644 --- a/jdk/src/share/classes/java/awt/TextComponent.java +++ b/jdk/src/share/classes/java/awt/TextComponent.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1995, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1995, 2014, Oracle and/or its affiliates. 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 @@ -107,6 +107,9 @@ public class TextComponent extends Component implements Accessible { // the background color of non-editable TextComponents. boolean backgroundSetByClientCode = false; + /** + * A list of listeners that will receive events from this object. + */ transient protected TextListener textListener; /* diff --git a/jdk/src/share/classes/java/awt/TextField.java b/jdk/src/share/classes/java/awt/TextField.java index 3b4646896e1..ebebc828b96 100644 --- a/jdk/src/share/classes/java/awt/TextField.java +++ b/jdk/src/share/classes/java/awt/TextField.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1995, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1995, 2014, Oracle and/or its affiliates. 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 @@ -272,6 +272,10 @@ public class TextField extends TextComponent { } /** + * Sets the character to be echoed when protected input is displayed. + * + * @param c the echo character for this text field + * * @deprecated As of JDK version 1.1, * replaced by setEchoChar(char). */ @@ -368,6 +372,12 @@ public class TextField extends TextComponent { } /** + * Returns the preferred size for this text field + * with the specified number of columns. + * + * @param columns the number of columns + * @return the preferred size for the text field + * * @deprecated As of JDK version 1.1, * replaced by getPreferredSize(int). */ @@ -407,8 +417,9 @@ public class TextField extends TextComponent { /** * Gets the minimum dimensions for a text field with * the specified number of columns. - * @param columns the number of columns in - * this text field. + * @param columns the number of columns in + * this text field. + * @return the minimum size for this text field * @since 1.1 */ public Dimension getMinimumSize(int columns) { @@ -416,6 +427,11 @@ public class TextField extends TextComponent { } /** + * Returns the minimum dimensions for a text field with + * the specified number of columns. + * + * @param columns the number of columns + * @return the minimum size for this text field * @deprecated As of JDK version 1.1, * replaced by getMinimumSize(int). */ diff --git a/jdk/src/share/classes/java/awt/Toolkit.java b/jdk/src/share/classes/java/awt/Toolkit.java index 7bc8c24f625..65b494ba52d 100644 --- a/jdk/src/share/classes/java/awt/Toolkit.java +++ b/jdk/src/share/classes/java/awt/Toolkit.java @@ -422,7 +422,8 @@ public abstract class Toolkit { * and allows the Component and Container classes to be extended directly * to create windowless components that are defined entirely in java. * - * @param target The Component to be created. + * @param target The Component to be created. + * @return the peer for the specified component */ protected LightweightPeer createComponent(Component target) { if (lightweightMarker == null) { @@ -1370,6 +1371,9 @@ public abstract class Toolkit { * {@link java.awt.event.KeyEvent#VK_SCROLL_LOCK VK_SCROLL_LOCK}, and * {@link java.awt.event.KeyEvent#VK_KANA_LOCK VK_KANA_LOCK}. * + * @param keyCode the key code + * @return {@code true} if the given key is currently in its "on" state; + * otherwise {@code false} * @exception java.lang.IllegalArgumentException if keyCode * is not one of the valid key codes * @exception java.lang.UnsupportedOperationException if the host system doesn't @@ -1404,6 +1408,8 @@ public abstract class Toolkit { * involve event processing and therefore may not be immediately * observable through getLockingKeyState. * + * @param keyCode the key code + * @param on the state of the key * @exception java.lang.IllegalArgumentException if keyCode * is not one of the valid key codes * @exception java.lang.UnsupportedOperationException if the host system doesn't @@ -1429,6 +1435,9 @@ public abstract class Toolkit { /** * Give native peers the ability to query the native container * given a native component (eg the direct parent may be lightweight). + * + * @param c the component to fetch the container for + * @return the native container object for the component */ protected static Container getNativeContainer(Component c) { return c.getNativeContainer(); @@ -1449,6 +1458,7 @@ public abstract class Toolkit { * @param name a localized description of the cursor, for Java Accessibility use * @exception IndexOutOfBoundsException if the hotSpot values are outside * the bounds of the cursor + * @return the cursor created * @exception HeadlessException if GraphicsEnvironment.isHeadless() * returns true * @see java.awt.GraphicsEnvironment#isHeadless @@ -1675,6 +1685,11 @@ public abstract class Toolkit { /** * Gets a property with the specified key and default. * This method returns defaultValue if the property is not found. + * + * @param key the key + * @param defaultValue the default value + * @return the value of the property or the default value + * if the property was not found */ public static String getProperty(String key, String defaultValue) { // first try platform specific bundle @@ -1738,6 +1753,9 @@ public abstract class Toolkit { * Creates the peer for a DragSourceContext. * Always throws InvalidDndOperationException if * GraphicsEnvironment.isHeadless() returns true. + * + * @param dge the {@code DragGestureEvent} + * @return the peer created * @see java.awt.GraphicsEnvironment#isHeadless */ public abstract DragSourceContextPeer createDragSourceContextPeer(DragGestureEvent dge) throws InvalidDnDOperationException; @@ -1775,6 +1793,9 @@ public abstract class Toolkit { * representation for an underlying platform dependent desktop setting. * For more information on desktop properties supported by the AWT see * AWT Desktop Properties. + * + * @param propertyName the property name + * @return the value for the specified desktop property */ public final synchronized Object getDesktopProperty(String propertyName) { // This is a workaround for headless toolkits. It would be @@ -1818,6 +1839,9 @@ public abstract class Toolkit { /** * Sets the named desktop property to the specified value and fires a * property change event to notify any listeners that the value has changed. + * + * @param name the property name + * @param newValue the new property value */ protected final void setDesktopProperty(String name, Object newValue) { // This is a workaround for headless toolkits. It would be diff --git a/jdk/src/share/classes/java/awt/Window.java b/jdk/src/share/classes/java/awt/Window.java index 47bcdf301ca..629f1df75a4 100644 --- a/jdk/src/share/classes/java/awt/Window.java +++ b/jdk/src/share/classes/java/awt/Window.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1995, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1995, 2014, Oracle and/or its affiliates. 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 @@ -1452,6 +1452,8 @@ public class Window extends Container implements Accessible { /** * Returns the owner of this window. + * + * @return the owner of this window * @since 1.2 */ public Window getOwner() { @@ -1464,6 +1466,8 @@ public class Window extends Container implements Accessible { /** * Return an array containing all the windows this * window currently owns. + * + * @return the array of all the owned windows * @since 1.2 */ public Window[] getOwnedWindows() { @@ -1586,6 +1590,7 @@ public class Window extends Container implements Accessible { * dialogs such as component positions, {@code LayoutManager}s * or serialization. * + * @return the array of all the {@code Window}s created by the application * @see Frame#getFrames * @see Window#getOwnerlessWindows * @@ -1608,6 +1613,8 @@ public class Window extends Container implements Accessible { * dialogs such as component positions, {@code LayoutManager}s * or serialization. * + * @return the array of all the ownerless {@code Window}s + * created by this application * @see Frame#getFrames * @see Window#getWindows() * @@ -2849,6 +2856,7 @@ public class Window extends Container implements Accessible { * * This method can only be called while the window is not displayable. * + * @param type the window type * @throws IllegalComponentStateException if the window * is displayable. * @throws IllegalArgumentException if the type is {@code null} @@ -2874,6 +2882,7 @@ public class Window extends Container implements Accessible { /** * Returns the type of the window. * + * @return the type of the window * @see #setType * @since 1.7 */