From 0b95f7c7a256fcc6e855070e510d3a8ec0d5e89a Mon Sep 17 00:00:00 2001 From: Steven Sides Date: Mon, 23 Jun 2014 10:57:22 +0400 Subject: [PATCH] 8040901: fix doclint block tag issues in swing event classes Reviewed-by: alexsch --- .../javax/swing/event/AncestorEvent.java | 8 +- .../javax/swing/event/AncestorListener.java | 11 ++- .../javax/swing/event/CellEditorListener.java | 14 +++- .../javax/swing/event/EventListenerList.java | 18 +++- .../javax/swing/event/HyperlinkEvent.java | 2 + .../swing/event/InternalFrameListener.java | 23 ++++- .../javax/swing/event/ListSelectionEvent.java | 1 + .../javax/swing/event/MenuKeyListener.java | 8 +- .../javax/swing/event/PopupMenuEvent.java | 4 +- .../javax/swing/event/PopupMenuListener.java | 8 +- .../swing/event/TableColumnModelEvent.java | 12 ++- .../swing/event/TableColumnModelListener.java | 28 +++++-- .../javax/swing/event/TableModelEvent.java | 84 +++++++++++++------ .../javax/swing/event/TableModelListener.java | 5 +- .../javax/swing/event/TreeExpansionEvent.java | 4 +- .../swing/event/TreeExpansionListener.java | 16 ++-- .../javax/swing/event/TreeModelListener.java | 45 +++++----- .../javax/swing/event/TreeSelectionEvent.java | 33 ++++++-- .../swing/event/TreeWillExpandListener.java | 10 ++- .../swing/event/UndoableEditListener.java | 4 +- .../javax/swing/tree/ExpandVetoException.java | 2 +- 21 files changed, 257 insertions(+), 83 deletions(-) diff --git a/jdk/src/share/classes/javax/swing/event/AncestorEvent.java b/jdk/src/share/classes/javax/swing/event/AncestorEvent.java index a113ebe4c0b..d6f7ab08c28 100644 --- a/jdk/src/share/classes/javax/swing/event/AncestorEvent.java +++ b/jdk/src/share/classes/javax/swing/event/AncestorEvent.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 @@ -81,6 +81,8 @@ public class AncestorEvent extends AWTEvent { /** * Returns the ancestor that the event actually occurred on. + * + * @return the {@code Container} object specifying the ancestor component */ public Container getAncestor() { return ancestor; @@ -90,6 +92,8 @@ public class AncestorEvent extends AWTEvent { * Returns the parent of the ancestor the event actually occurred on. * This is most interesting in an ANCESTOR_REMOVED event, as * the ancestor may no longer be in the component hierarchy. + * + * @return the {@code Container} object specifying the ancestor's parent */ public Container getAncestorParent() { return ancestorParent; @@ -97,6 +101,8 @@ public class AncestorEvent extends AWTEvent { /** * Returns the component that the listener was added to. + * + * @return the {@code JComponent} on which the event occurred */ public JComponent getComponent() { return (JComponent)getSource(); diff --git a/jdk/src/share/classes/javax/swing/event/AncestorListener.java b/jdk/src/share/classes/javax/swing/event/AncestorListener.java index d0b07bdbfea..30dd3cfc4f1 100644 --- a/jdk/src/share/classes/javax/swing/event/AncestorListener.java +++ b/jdk/src/share/classes/javax/swing/event/AncestorListener.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1997, 1998, 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 @@ -48,6 +48,9 @@ public interface AncestorListener extends EventListener { * if the source has actually become visible. For this to be true * all its parents must be visible and it must be in a hierarchy * rooted at a Window + * + * @param event an {@code AncestorEvent} signifying a change in an + * ancestor-component's display-status */ public void ancestorAdded(AncestorEvent event); @@ -58,11 +61,17 @@ public interface AncestorListener extends EventListener { * if the source has actually become invisible. For this to be true * at least one of its parents must by invisible or it is not in * a hierarchy rooted at a Window + * + * @param event an {@code AncestorEvent} signifying a change in an + * ancestor-component's display-status */ public void ancestorRemoved(AncestorEvent event); /** * Called when either the source or one of its ancestors is moved. + * + * @param event an {@code AncestorEvent} signifying a change in an + * ancestor-component's display-status */ public void ancestorMoved(AncestorEvent event); diff --git a/jdk/src/share/classes/javax/swing/event/CellEditorListener.java b/jdk/src/share/classes/javax/swing/event/CellEditorListener.java index fabeca11f62..817e6ea2441 100644 --- a/jdk/src/share/classes/javax/swing/event/CellEditorListener.java +++ b/jdk/src/share/classes/javax/swing/event/CellEditorListener.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1997, 1998, 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 @@ -37,9 +37,17 @@ import java.util.EventListener; public interface CellEditorListener extends java.util.EventListener { - /** This tells the listeners the editor has ended editing */ + /** + * This tells the listeners the editor has ended editing + * + * @param e the {@code ChangeEvent} containing the source of the event + */ public void editingStopped(ChangeEvent e); - /** This tells the listeners the editor has canceled editing */ + /** + * This tells the listeners the editor has canceled editing + * + * @param e the {@code ChangeEvent} containing the source of the event + */ public void editingCanceled(ChangeEvent e); } diff --git a/jdk/src/share/classes/javax/swing/event/EventListenerList.java b/jdk/src/share/classes/javax/swing/event/EventListenerList.java index 9e145daa251..ccde0bfef76 100644 --- a/jdk/src/share/classes/javax/swing/event/EventListenerList.java +++ b/jdk/src/share/classes/javax/swing/event/EventListenerList.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 @@ -120,6 +120,8 @@ public class EventListenerList implements Serializable { * any such manipulation is necessary, it should be done * on a copy of the array returned rather than the array * itself. + * + * @return array of ListenerType-listener pairs */ public Object[] getListenerList() { return listenerList; @@ -127,6 +129,9 @@ public class EventListenerList implements Serializable { /** * Return an array of all the listeners of the given type. + * + * @param the type of {@code EventListener} to search for + * @param t the type of {@code EventListener} classes to be returned * @return all of the listeners of the specified type. * @exception ClassCastException if the supplied class * is not assignable to EventListener @@ -148,6 +153,8 @@ public class EventListenerList implements Serializable { /** * Returns the total number of listeners for this listener list. + * + * @return an integer count of total number of listeners */ public int getListenerCount() { return listenerList.length/2; @@ -156,6 +163,9 @@ public class EventListenerList implements Serializable { /** * Returns the total number of listeners of the supplied type * for this listener list. + * + * @param t the type of listeners to count + * @return the number of listeners of type {@code t} */ public int getListenerCount(Class t) { Object[] lList = listenerList; @@ -173,7 +183,9 @@ public class EventListenerList implements Serializable { /** * Adds the listener as a listener of the specified type. - * @param t the type of the listener to be added + * + * @param the type of {@code EventListener} to add + * @param t the type of the {@code EventListener} class to add * @param l the listener to be added */ public synchronized void add(Class t, T l) { @@ -206,6 +218,8 @@ public class EventListenerList implements Serializable { /** * Removes the listener as a listener of the specified type. + * + * @param the type of {@code EventListener} * @param t the type of the listener to be removed * @param l the listener to be removed */ diff --git a/jdk/src/share/classes/javax/swing/event/HyperlinkEvent.java b/jdk/src/share/classes/javax/swing/event/HyperlinkEvent.java index 848910188e9..bcd7ea60063 100644 --- a/jdk/src/share/classes/javax/swing/event/HyperlinkEvent.java +++ b/jdk/src/share/classes/javax/swing/event/HyperlinkEvent.java @@ -142,6 +142,8 @@ public class HyperlinkEvent extends EventObject { * This may be useful if a URL can't be formed * from the description, in which case the associated * URL would be null. + * + * @return the description of this link as a {@code String} */ public String getDescription() { return desc; diff --git a/jdk/src/share/classes/javax/swing/event/InternalFrameListener.java b/jdk/src/share/classes/javax/swing/event/InternalFrameListener.java index 151c4978630..433f20e6227 100644 --- a/jdk/src/share/classes/javax/swing/event/InternalFrameListener.java +++ b/jdk/src/share/classes/javax/swing/event/InternalFrameListener.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1998, 2013, 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 @@ -42,6 +42,9 @@ import java.util.EventListener; public interface InternalFrameListener extends EventListener { /** * Invoked when a internal frame has been opened. + * + * @param e an {@code InternalFrameEvent} with information about the + * {@code JInteralFrame} that originated the event * @see javax.swing.JInternalFrame#show */ public void internalFrameOpened(InternalFrameEvent e); @@ -49,36 +52,54 @@ public interface InternalFrameListener extends EventListener { /** * Invoked when an internal frame is in the process of being closed. * The close operation can be overridden at this point. + * + * @param e an {@code InternalFrameEvent} with information about the + * {@code JInteralFrame} that originated the event * @see javax.swing.JInternalFrame#setDefaultCloseOperation */ public void internalFrameClosing(InternalFrameEvent e); /** * Invoked when an internal frame has been closed. + * + * @param e an {@code InternalFrameEvent} with information about the + * {@code JInteralFrame} that originated the event * @see javax.swing.JInternalFrame#setClosed */ public void internalFrameClosed(InternalFrameEvent e); /** * Invoked when an internal frame is iconified. + * + * @param e an {@code InternalFrameEvent} with information about the + * {@code JInteralFrame} that originated the event * @see javax.swing.JInternalFrame#setIcon */ public void internalFrameIconified(InternalFrameEvent e); /** * Invoked when an internal frame is de-iconified. + * + * @param e an {@code InternalFrameEvent} with information about the + * {@code JInteralFrame} that originated the event * @see javax.swing.JInternalFrame#setIcon */ public void internalFrameDeiconified(InternalFrameEvent e); /** * Invoked when an internal frame is activated. + * + * @param e an {@code InternalFrameEvent} with information about the + * {@code JInteralFrame} that originated the event * @see javax.swing.JInternalFrame#setSelected */ public void internalFrameActivated(InternalFrameEvent e); /** * Invoked when an internal frame is de-activated. + * + * @param e an {@code InternalFrameEvent} with information about the + * {@code JInteralFrame} that originated the event * @see javax.swing.JInternalFrame#setSelected */ public void internalFrameDeactivated(InternalFrameEvent e); diff --git a/jdk/src/share/classes/javax/swing/event/ListSelectionEvent.java b/jdk/src/share/classes/javax/swing/event/ListSelectionEvent.java index a5128f1e47c..735b5797088 100644 --- a/jdk/src/share/classes/javax/swing/event/ListSelectionEvent.java +++ b/jdk/src/share/classes/javax/swing/event/ListSelectionEvent.java @@ -63,6 +63,7 @@ public class ListSelectionEvent extends EventObject * {@code lastIndex}. The selection of at least one index within the range will * have changed. * + * @param source the {@code Object} on which the event initially occurred * @param firstIndex the first index in the range, <= lastIndex * @param lastIndex the last index in the range, >= firstIndex * @param isAdjusting whether or not this is one in a series of diff --git a/jdk/src/share/classes/javax/swing/event/MenuKeyListener.java b/jdk/src/share/classes/javax/swing/event/MenuKeyListener.java index 7caaf2a609f..3abcced7815 100644 --- a/jdk/src/share/classes/javax/swing/event/MenuKeyListener.java +++ b/jdk/src/share/classes/javax/swing/event/MenuKeyListener.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1998, 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 @@ -37,16 +37,22 @@ public interface MenuKeyListener extends EventListener { /** * Invoked when a key has been typed. * This event occurs when a key press is followed by a key release. + * + * @param e a {@code MenuKeyEvent} */ void menuKeyTyped(MenuKeyEvent e); /** * Invoked when a key has been pressed. + * + * @param e a {@code MenuKeyEvent} */ void menuKeyPressed(MenuKeyEvent e); /** * Invoked when a key has been released. + * + * @param e a {@code MenuKeyEvent} */ void menuKeyReleased(MenuKeyEvent e); } diff --git a/jdk/src/share/classes/javax/swing/event/PopupMenuEvent.java b/jdk/src/share/classes/javax/swing/event/PopupMenuEvent.java index 0668371939f..4431dcc0642 100644 --- a/jdk/src/share/classes/javax/swing/event/PopupMenuEvent.java +++ b/jdk/src/share/classes/javax/swing/event/PopupMenuEvent.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 @@ -27,7 +27,7 @@ package javax.swing.event; import java.util.EventObject; /** - * PopupMenuEvent only contains the source of the event which is the JPoupMenu + * PopupMenuEvent only contains the source of the event which is the JPopupMenu * sending the event *

* Warning: diff --git a/jdk/src/share/classes/javax/swing/event/PopupMenuListener.java b/jdk/src/share/classes/javax/swing/event/PopupMenuListener.java index 4f8b5223664..6f498733f27 100644 --- a/jdk/src/share/classes/javax/swing/event/PopupMenuListener.java +++ b/jdk/src/share/classes/javax/swing/event/PopupMenuListener.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1997, 1998, 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 @@ -35,17 +35,23 @@ public interface PopupMenuListener extends EventListener { /** * This method is called before the popup menu becomes visible + * + * @param e a {@code PopupMenuEvent} containing the source of the event */ void popupMenuWillBecomeVisible(PopupMenuEvent e); /** * This method is called before the popup menu becomes invisible * Note that a JPopupMenu can become invisible any time + * + * @param e a {@code PopupMenuEvent} containing the source of the event */ void popupMenuWillBecomeInvisible(PopupMenuEvent e); /** * This method is called when the popup menu is canceled + * + * @param e a {@code PopupMenuEvent} containing the source of the event */ void popupMenuCanceled(PopupMenuEvent e); } diff --git a/jdk/src/share/classes/javax/swing/event/TableColumnModelEvent.java b/jdk/src/share/classes/javax/swing/event/TableColumnModelEvent.java index 1958ded5e39..7293238671b 100644 --- a/jdk/src/share/classes/javax/swing/event/TableColumnModelEvent.java +++ b/jdk/src/share/classes/javax/swing/event/TableColumnModelEvent.java @@ -83,9 +83,17 @@ public class TableColumnModelEvent extends java.util.EventObject // Querying Methods // - /** Returns the fromIndex. Valid for removed or moved events */ + /** + * Returns the fromIndex. Valid for removed or moved events + * + * @return int value for index from which the column was moved or removed + */ public int getFromIndex() { return fromIndex; }; - /** Returns the toIndex. Valid for add and moved events */ + /** + * Returns the toIndex. Valid for add and moved events + * + * @return int value of column's new index + */ public int getToIndex() { return toIndex; }; } diff --git a/jdk/src/share/classes/javax/swing/event/TableColumnModelListener.java b/jdk/src/share/classes/javax/swing/event/TableColumnModelListener.java index ccd6e5dd88d..deabfe7e8ba 100644 --- a/jdk/src/share/classes/javax/swing/event/TableColumnModelListener.java +++ b/jdk/src/share/classes/javax/swing/event/TableColumnModelListener.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1997, 1998, 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 @@ -39,21 +39,39 @@ import java.util.EventListener; public interface TableColumnModelListener extends java.util.EventListener { - /** Tells listeners that a column was added to the model. */ + /** + * Tells listeners that a column was added to the model. + * + * @param e a {@code TableColumnModelEvent} + */ public void columnAdded(TableColumnModelEvent e); - /** Tells listeners that a column was removed from the model. */ + /** + * Tells listeners that a column was removed from the model. + * + * @param e a {@code TableColumnModelEvent} + */ public void columnRemoved(TableColumnModelEvent e); - /** Tells listeners that a column was repositioned. */ + /** + * Tells listeners that a column was repositioned. + * + * @param e a {@code TableColumnModelEvent} + */ public void columnMoved(TableColumnModelEvent e); - /** Tells listeners that a column was moved due to a margin change. */ + /** + * Tells listeners that a column was moved due to a margin change. + * + * @param e a {@code ChangeEvent} + */ public void columnMarginChanged(ChangeEvent e); /** * Tells listeners that the selection model of the * TableColumnModel changed. + * + * @param e a {@code ListSelectionEvent} */ public void columnSelectionChanged(ListSelectionEvent e); } diff --git a/jdk/src/share/classes/javax/swing/event/TableModelEvent.java b/jdk/src/share/classes/javax/swing/event/TableModelEvent.java index 0247f992a4d..bf6555c4aac 100644 --- a/jdk/src/share/classes/javax/swing/event/TableModelEvent.java +++ b/jdk/src/share/classes/javax/swing/event/TableModelEvent.java @@ -95,13 +95,15 @@ public class TableModelEvent extends java.util.EventObject // /** - * All row data in the table has changed, listeners should discard any state - * that was based on the rows and requery the TableModel - * to get the new row count and all the appropriate values. - * The JTable will repaint the entire visible region on - * receiving this event, querying the model for the cell values that are visible. - * The structure of the table ie, the column names, types and order - * have not changed. + * All row data in the table has changed, listeners should discard any state + * that was based on the rows and requery the TableModel + * to get the new row count and all the appropriate values. + * The JTable will repaint the entire visible region on + * receiving this event, querying the model for the cell values that are visible. + * The structure of the table ie, the column names, types and order + * have not changed. + * + * @param source the {@code TableModel} affected by this event */ public TableModelEvent(TableModel source) { // Use Integer.MAX_VALUE instead of getRowCount() in case rows were deleted. @@ -109,21 +111,28 @@ public class TableModelEvent extends java.util.EventObject } /** - * This row of data has been updated. - * To denote the arrival of a completely new table with a different structure - * use HEADER_ROW as the value for the row. - * When the JTable receives this event and its - * autoCreateColumnsFromModel - * flag is set it discards any TableColumns that it had and reallocates - * default ones in the order they appear in the model. This is the - * same as calling setModel(TableModel) on the JTable. + * This row of data has been updated. + * To denote the arrival of a completely new table with a different structure + * use HEADER_ROW as the value for the row. + * When the JTable receives this event and its + * autoCreateColumnsFromModel + * flag is set it discards any TableColumns that it had and reallocates + * default ones in the order they appear in the model. This is the + * same as calling setModel(TableModel) on the JTable. + * + * @param source the {@code TableModel} affected by this event + * @param row the row which has been updated */ public TableModelEvent(TableModel source, int row) { this(source, row, row, ALL_COLUMNS, UPDATE); } /** - * The data in rows [firstRow, lastRow] have been updated. + * The data in rows [firstRow, lastRow] have been updated. + * + * @param source the {@code TableModel} affected by this event + * @param firstRow the first row affected by this event + * @param lastRow the last row affected by this event */ public TableModelEvent(TableModel source, int firstRow, int lastRow) { this(source, firstRow, lastRow, ALL_COLUMNS, UPDATE); @@ -132,18 +141,32 @@ public class TableModelEvent extends java.util.EventObject /** * The cells in column column in the range * [firstRow, lastRow] have been updated. + * + * @param source the {@code TableModel} affected by this event + * @param firstRow the first row affected by this event + * @param lastRow the last row affected by this event + * @param column the column index of cells changed; {@code ALL_COLUMNS} + * signifies all cells in the specified range of rows are changed. */ public TableModelEvent(TableModel source, int firstRow, int lastRow, int column) { this(source, firstRow, lastRow, column, UPDATE); } /** - * The cells from (firstRow, column) to (lastRow, column) have been changed. - * The column refers to the column index of the cell in the model's - * co-ordinate system. When column is ALL_COLUMNS, all cells in the - * specified range of rows are considered changed. - *

- * The type should be one of: INSERT, UPDATE and DELETE. + * The cells from (firstRow, column) to (lastRow, column) have been changed. + * The column refers to the column index of the cell in the model's + * co-ordinate system. When column is ALL_COLUMNS, all cells in the + * specified range of rows are considered changed. + *

+ * The type should be one of: INSERT, UPDATE and DELETE. + * + * @param source the {@code TableModel} affected by this event + * @param firstRow the first row affected by this event + * @param lastRow the last row affected by this event + * @param column the column index of cells changed; {@code ALL_COLUMNS} + * signifies all cells in the specified range of rows are changed. + * @param type the type of change signified by this even, @code INSERT}, + * {@code DELETE } or {@code UPDATE} */ public TableModelEvent(TableModel source, int firstRow, int lastRow, int column, int type) { super(source); @@ -157,23 +180,36 @@ public class TableModelEvent extends java.util.EventObject // Querying Methods // - /** Returns the first row that changed. HEADER_ROW means the meta data, + /** + * Returns the first row that changed. HEADER_ROW means the meta data, * ie. names, types and order of the columns. + * + * @return an integer signifying the first row changed */ public int getFirstRow() { return firstRow; }; - /** Returns the last row that changed. */ + /** + * Returns the last row that changed. + * + * @return an integer signifying the last row changed + */ public int getLastRow() { return lastRow; }; /** * Returns the column for the event. If the return * value is ALL_COLUMNS; it means every column in the specified * rows changed. + * + * @return an integer signifying which column is affected by this event */ public int getColumn() { return column; }; /** * Returns the type of event - one of: INSERT, UPDATE and DELETE. + * + * @return the type of change to a table model, an {@code INSERT} or + * {@code DELETE } of row(s) or column(s) or {@code UPDATE} + * to data */ public int getType() { return type; } } diff --git a/jdk/src/share/classes/javax/swing/event/TableModelListener.java b/jdk/src/share/classes/javax/swing/event/TableModelListener.java index 9dce6700238..e32c2ef84f5 100644 --- a/jdk/src/share/classes/javax/swing/event/TableModelListener.java +++ b/jdk/src/share/classes/javax/swing/event/TableModelListener.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1997, 1998, 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 @@ -40,6 +40,9 @@ public interface TableModelListener extends java.util.EventListener /** * This fine grain notification tells listeners the exact range * of cells, rows, or columns that changed. + * + * @param e a {@code TableModelEvent} to notify listener that a table model + * has changed */ public void tableChanged(TableModelEvent e); } diff --git a/jdk/src/share/classes/javax/swing/event/TreeExpansionEvent.java b/jdk/src/share/classes/javax/swing/event/TreeExpansionEvent.java index 1e70200b2e7..7f8f37a1d5d 100644 --- a/jdk/src/share/classes/javax/swing/event/TreeExpansionEvent.java +++ b/jdk/src/share/classes/javax/swing/event/TreeExpansionEvent.java @@ -54,7 +54,7 @@ public class TreeExpansionEvent extends EventObject /** * Path to the value this event represents. */ - protected TreePath path; + protected TreePath path; /** * Constructs a TreeExpansionEvent object. @@ -71,6 +71,8 @@ public class TreeExpansionEvent extends EventObject /** * Returns the path to the value that has been expanded/collapsed. + * + * @return this event's {@code TreePath} object */ public TreePath getPath() { return path; } } diff --git a/jdk/src/share/classes/javax/swing/event/TreeExpansionListener.java b/jdk/src/share/classes/javax/swing/event/TreeExpansionListener.java index 915dcf942f9..a71ac4045c0 100644 --- a/jdk/src/share/classes/javax/swing/event/TreeExpansionListener.java +++ b/jdk/src/share/classes/javax/swing/event/TreeExpansionListener.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 @@ -41,12 +41,18 @@ import java.util.EventListener; public interface TreeExpansionListener extends EventListener { /** - * Called whenever an item in the tree has been expanded. - */ + * Called whenever an item in the tree has been expanded. + * + * @param event a {@code TreeExpansionEvent} containing a {@code TreePath} + * object for the expanded node + */ public void treeExpanded(TreeExpansionEvent event); /** - * Called whenever an item in the tree has been collapsed. - */ + * Called whenever an item in the tree has been collapsed. + * + * @param event a {@code TreeExpansionEvent} containing a {@code TreePath} + * object for the collapsed node + */ public void treeCollapsed(TreeExpansionEvent event); } diff --git a/jdk/src/share/classes/javax/swing/event/TreeModelListener.java b/jdk/src/share/classes/javax/swing/event/TreeModelListener.java index d89c2a39ef0..22712810fda 100644 --- a/jdk/src/share/classes/javax/swing/event/TreeModelListener.java +++ b/jdk/src/share/classes/javax/swing/event/TreeModelListener.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 @@ -46,25 +46,26 @@ public interface TreeModelListener extends EventListener { * altered their children arrays, but other attributes have * changed and may affect presentation. Example: the name of a * file has changed, but it is in the same location in the file - * system.

- *

To indicate the root has changed, childIndices and children - * will be null.

+ * system. * - *

Use e.getPath() - * to get the parent of the changed node(s). - * e.getChildIndices() - * returns the index(es) of the changed node(s).

+ *

To indicate the root has changed, childIndices and children + * will be null. + * + *

Use {@code e.getPath()} to get the parent of the changed node(s). + * {@code e.getChildIndices()} returns the index(es) of the changed node(s). + * + * @param e a {@code TreeModelEvent} describing changes to a tree model */ void treeNodesChanged(TreeModelEvent e); /** *

Invoked after nodes have been inserted into the tree.

* - *

Use e.getPath() - * to get the parent of the new node(s). - * e.getChildIndices() - * returns the index(es) of the new node(s) - * in ascending order.

+ *

Use {@code e.getPath()} to get the parent of the new node(s). + * {@code e.getChildIndices()} returns the index(es) of the new node(s) + * in ascending order. + * + * @param e a {@code TreeModelEvent} describing changes to a tree model */ void treeNodesInserted(TreeModelEvent e); @@ -74,11 +75,11 @@ public interface TreeModelListener extends EventListener { * invoked once for the root of the removed subtree, not once for * each individual set of siblings removed.

* - *

Use e.getPath() - * to get the former parent of the deleted node(s). - * e.getChildIndices() - * returns, in ascending order, the index(es) - * the node(s) had before being deleted.

+ *

Use {@code e.getPath()} to get the former parent of the deleted + * node(s). {@code e.getChildIndices()} returns, in ascending order, the + * index(es) the node(s) had before being deleted. + * + * @param e a {@code TreeModelEvent} describing changes to a tree model */ void treeNodesRemoved(TreeModelEvent e); @@ -88,10 +89,10 @@ public interface TreeModelListener extends EventListener { * one and the first element does not identify the current root node * the first element should become the new root of the tree. * - *

Use e.getPath() - * to get the path to the node. - * e.getChildIndices() - * returns null.

+ *

Use {@code e.getPath()} to get the path to the node. + * {@code e.getChildIndices()} returns null. + * + * @param e a {@code TreeModelEvent} describing changes to a tree model */ void treeStructureChanged(TreeModelEvent e); diff --git a/jdk/src/share/classes/javax/swing/event/TreeSelectionEvent.java b/jdk/src/share/classes/javax/swing/event/TreeSelectionEvent.java index 792ce190509..32de1e9f517 100644 --- a/jdk/src/share/classes/javax/swing/event/TreeSelectionEvent.java +++ b/jdk/src/share/classes/javax/swing/event/TreeSelectionEvent.java @@ -62,12 +62,16 @@ public class TreeSelectionEvent extends EventObject protected TreePath newLeadSelectionPath; /** - * Represents a change in the selection of a TreeSelectionModel. - * paths identifies the paths that have been either added or + * Represents a change in the selection of a {@code TreeSelectionModel}. + * {@code paths} identifies the paths that have been either added or * removed from the selection. * * @param source source of event * @param paths the paths that have changed in the selection + * @param areNew a {@code boolean} array indicating whether the paths in + * {@code paths} are new to the selection + * @param oldLeadSelectionPath the previous lead selection path + * @param newLeadSelectionPath the new lead selection path */ public TreeSelectionEvent(Object source, TreePath[] paths, boolean[] areNew, TreePath oldLeadSelectionPath, @@ -81,14 +85,16 @@ public class TreeSelectionEvent extends EventObject } /** - * Represents a change in the selection of a TreeSelectionModel. - * path identifies the path that have been either added or + * Represents a change in the selection of a {@code TreeSelectionModel}. + * {@code path} identifies the path that has been either added or * removed from the selection. * * @param source source of event * @param path the path that has changed in the selection * @param isNew whether or not the path is new to the selection, false - * means path was removed from the selection. + * means path was removed from the selection. + * @param oldLeadSelectionPath the previous lead selection path + * @param newLeadSelectionPath the new lead selection path */ public TreeSelectionEvent(Object source, TreePath path, boolean isNew, TreePath oldLeadSelectionPath, @@ -104,8 +110,9 @@ public class TreeSelectionEvent extends EventObject } /** - * Returns the paths that have been added or removed from the - * selection. + * Returns the paths that have been added or removed from the selection. + * + * @return copy of the array of {@code TreePath} obects for this event. */ public TreePath[] getPaths() { @@ -120,6 +127,8 @@ public class TreeSelectionEvent extends EventObject /** * Returns the first path element. + * + * @return the first {@code TreePath} element represented by this event */ public TreePath getPath() { @@ -187,6 +196,8 @@ public class TreeSelectionEvent extends EventObject /** * Returns the path that was previously the lead path. + * + * @return a {@code TreePath} containing the old lead selection path */ public TreePath getOldLeadSelectionPath() { return oldLeadSelectionPath; @@ -194,6 +205,8 @@ public class TreeSelectionEvent extends EventObject /** * Returns the current lead path. + * + * @return a {@code TreePath} containing the new lead selection path */ public TreePath getNewLeadSelectionPath() { return newLeadSelectionPath; @@ -201,10 +214,14 @@ public class TreeSelectionEvent extends EventObject /** * Returns a copy of the receiver, but with the source being newSource. + * + * @param newSource source of event + * @return an {@code Object} which is a copy of this event with the source + * being the {@code newSource} provided */ public Object cloneWithSource(Object newSource) { // Fix for IE bug - crashing - return new TreeSelectionEvent(newSource, paths,areNew, + return new TreeSelectionEvent(newSource, paths, areNew, oldLeadSelectionPath, newLeadSelectionPath); } diff --git a/jdk/src/share/classes/javax/swing/event/TreeWillExpandListener.java b/jdk/src/share/classes/javax/swing/event/TreeWillExpandListener.java index 6fd170c862a..ad5691220ef 100644 --- a/jdk/src/share/classes/javax/swing/event/TreeWillExpandListener.java +++ b/jdk/src/share/classes/javax/swing/event/TreeWillExpandListener.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1998, 2013, 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 @@ -41,11 +41,19 @@ import javax.swing.tree.ExpandVetoException; public interface TreeWillExpandListener extends EventListener { /** * Invoked whenever a node in the tree is about to be expanded. + * + * @param event a {@code TreeExpansionEvent} containing a {@code TreePath} + * object for the node + * @throws ExpandVetoException to signify expansion has been canceled */ public void treeWillExpand(TreeExpansionEvent event) throws ExpandVetoException; /** * Invoked whenever a node in the tree is about to be collapsed. + * + * @param event a {@code TreeExpansionEvent} containing a {@code TreePath} + * object for the node + * @throws ExpandVetoException to signify collapse has been canceled */ public void treeWillCollapse(TreeExpansionEvent event) throws ExpandVetoException; } diff --git a/jdk/src/share/classes/javax/swing/event/UndoableEditListener.java b/jdk/src/share/classes/javax/swing/event/UndoableEditListener.java index ba95d93b980..9db6991eb1b 100644 --- a/jdk/src/share/classes/javax/swing/event/UndoableEditListener.java +++ b/jdk/src/share/classes/javax/swing/event/UndoableEditListener.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1997, 1998, 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 @@ -38,6 +38,8 @@ public interface UndoableEditListener extends java.util.EventListener { /** * An undoable edit happened + * + * @param e an {@code UndoableEditEvent} object */ void undoableEditHappened(UndoableEditEvent e); } diff --git a/jdk/src/share/classes/javax/swing/tree/ExpandVetoException.java b/jdk/src/share/classes/javax/swing/tree/ExpandVetoException.java index 9fd6addb446..b35214771a0 100644 --- a/jdk/src/share/classes/javax/swing/tree/ExpandVetoException.java +++ b/jdk/src/share/classes/javax/swing/tree/ExpandVetoException.java @@ -28,7 +28,7 @@ package javax.swing.tree; import javax.swing.event.TreeExpansionEvent; /** - * Exception used to stop and expand/collapse from happening. + * Exception used to stop an expand/collapse from happening. * See How to Write a Tree-Will-Expand Listener * in The Java Tutorial