8040901: fix doclint block tag issues in swing event classes
Reviewed-by: alexsch
Contributed-by: Steven Sides <steve.sides@oracle.com>
--- a/jdk/src/share/classes/javax/swing/event/AncestorEvent.java Fri Jun 20 10:10:27 2014 -0700
+++ b/jdk/src/share/classes/javax/swing/event/AncestorEvent.java Mon Jun 23 10:57:22 2014 +0400
@@ -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 @@
/**
* 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 @@
* 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 @@
/**
* Returns the component that the listener was added to.
+ *
+ * @return the {@code JComponent} on which the event occurred
*/
public JComponent getComponent() {
return (JComponent)getSource();
--- a/jdk/src/share/classes/javax/swing/event/AncestorListener.java Fri Jun 20 10:10:27 2014 -0700
+++ b/jdk/src/share/classes/javax/swing/event/AncestorListener.java Mon Jun 23 10:57:22 2014 +0400
@@ -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 @@
* 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 @@
* 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);
--- a/jdk/src/share/classes/javax/swing/event/CellEditorListener.java Fri Jun 20 10:10:27 2014 -0700
+++ b/jdk/src/share/classes/javax/swing/event/CellEditorListener.java Mon Jun 23 10:57:22 2014 +0400
@@ -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 @@
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);
}
--- a/jdk/src/share/classes/javax/swing/event/EventListenerList.java Fri Jun 20 10:10:27 2014 -0700
+++ b/jdk/src/share/classes/javax/swing/event/EventListenerList.java Mon Jun 23 10:57:22 2014 +0400
@@ -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 @@
* 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 @@
/**
* Return an array of all the listeners of the given type.
+ *
+ * @param <T> 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* Adds the listener as a listener of the specified type.
- * @param t the type of the listener to be added
+ *
+ * @param <T> 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 <T extends EventListener> void add(Class<T> t, T l) {
@@ -206,6 +218,8 @@
/**
* Removes the listener as a listener of the specified type.
+ *
+ * @param <T> the type of {@code EventListener}
* @param t the type of the listener to be removed
* @param l the listener to be removed
*/
--- a/jdk/src/share/classes/javax/swing/event/HyperlinkEvent.java Fri Jun 20 10:10:27 2014 -0700
+++ b/jdk/src/share/classes/javax/swing/event/HyperlinkEvent.java Mon Jun 23 10:57:22 2014 +0400
@@ -142,6 +142,8 @@
* 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;
--- a/jdk/src/share/classes/javax/swing/event/InternalFrameListener.java Fri Jun 20 10:10:27 2014 -0700
+++ b/jdk/src/share/classes/javax/swing/event/InternalFrameListener.java Mon Jun 23 10:57:22 2014 +0400
@@ -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 @@
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 @@
/**
* 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);
--- a/jdk/src/share/classes/javax/swing/event/ListSelectionEvent.java Fri Jun 20 10:10:27 2014 -0700
+++ b/jdk/src/share/classes/javax/swing/event/ListSelectionEvent.java Mon Jun 23 10:57:22 2014 +0400
@@ -63,6 +63,7 @@
* {@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
--- a/jdk/src/share/classes/javax/swing/event/MenuKeyListener.java Fri Jun 20 10:10:27 2014 -0700
+++ b/jdk/src/share/classes/javax/swing/event/MenuKeyListener.java Mon Jun 23 10:57:22 2014 +0400
@@ -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 @@
/**
* 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);
}
--- a/jdk/src/share/classes/javax/swing/event/PopupMenuEvent.java Fri Jun 20 10:10:27 2014 -0700
+++ b/jdk/src/share/classes/javax/swing/event/PopupMenuEvent.java Mon Jun 23 10:57:22 2014 +0400
@@ -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 @@
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
* <p>
* <strong>Warning:</strong>
--- a/jdk/src/share/classes/javax/swing/event/PopupMenuListener.java Fri Jun 20 10:10:27 2014 -0700
+++ b/jdk/src/share/classes/javax/swing/event/PopupMenuListener.java Mon Jun 23 10:57:22 2014 +0400
@@ -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 @@
/**
* 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);
}
--- a/jdk/src/share/classes/javax/swing/event/TableColumnModelEvent.java Fri Jun 20 10:10:27 2014 -0700
+++ b/jdk/src/share/classes/javax/swing/event/TableColumnModelEvent.java Mon Jun 23 10:57:22 2014 +0400
@@ -83,9 +83,17 @@
// 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; };
}
--- a/jdk/src/share/classes/javax/swing/event/TableColumnModelListener.java Fri Jun 20 10:10:27 2014 -0700
+++ b/jdk/src/share/classes/javax/swing/event/TableColumnModelListener.java Mon Jun 23 10:57:22 2014 +0400
@@ -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 @@
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);
}
--- a/jdk/src/share/classes/javax/swing/event/TableModelEvent.java Fri Jun 20 10:10:27 2014 -0700
+++ b/jdk/src/share/classes/javax/swing/event/TableModelEvent.java Mon Jun 23 10:57:22 2014 +0400
@@ -95,13 +95,15 @@
//
/**
- * All row data in the table has changed, listeners should discard any state
- * that was based on the rows and requery the <code>TableModel</code>
- * to get the new row count and all the appropriate values.
- * The <code>JTable</code> 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 <code>TableModel</code>
+ * to get the new row count and all the appropriate values.
+ * The <code>JTable</code> 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 @@
}
/**
- * This row of data has been updated.
- * To denote the arrival of a completely new table with a different structure
- * use <code>HEADER_ROW</code> as the value for the <code>row</code>.
- * When the <code>JTable</code> receives this event and its
- * <code>autoCreateColumnsFromModel</code>
- * 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 <code>setModel(TableModel)</code> on the <code>JTable</code>.
+ * This row of data has been updated.
+ * To denote the arrival of a completely new table with a different structure
+ * use <code>HEADER_ROW</code> as the value for the <code>row</code>.
+ * When the <code>JTable</code> receives this event and its
+ * <code>autoCreateColumnsFromModel</code>
+ * 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 <code>setModel(TableModel)</code> on the <code>JTable</code>.
+ *
+ * @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 [<I>firstRow</I>, <I>lastRow</I>] have been updated.
+ * The data in rows [<I>firstRow</I>, <I>lastRow</I>] 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 @@
/**
* The cells in column <I>column</I> in the range
* [<I>firstRow</I>, <I>lastRow</I>] 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 <I>column</I> refers to the column index of the cell in the model's
- * co-ordinate system. When <I>column</I> is ALL_COLUMNS, all cells in the
- * specified range of rows are considered changed.
- * <p>
- * The <I>type</I> should be one of: INSERT, UPDATE and DELETE.
+ * The cells from (firstRow, column) to (lastRow, column) have been changed.
+ * The <I>column</I> refers to the column index of the cell in the model's
+ * co-ordinate system. When <I>column</I> is ALL_COLUMNS, all cells in the
+ * specified range of rows are considered changed.
+ * <p>
+ * The <I>type</I> 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 @@
// 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; }
}
--- a/jdk/src/share/classes/javax/swing/event/TableModelListener.java Fri Jun 20 10:10:27 2014 -0700
+++ b/jdk/src/share/classes/javax/swing/event/TableModelListener.java Mon Jun 23 10:57:22 2014 +0400
@@ -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 @@
/**
* 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);
}
--- a/jdk/src/share/classes/javax/swing/event/TreeExpansionEvent.java Fri Jun 20 10:10:27 2014 -0700
+++ b/jdk/src/share/classes/javax/swing/event/TreeExpansionEvent.java Mon Jun 23 10:57:22 2014 +0400
@@ -54,7 +54,7 @@
/**
* Path to the value this event represents.
*/
- protected TreePath path;
+ protected TreePath path;
/**
* Constructs a TreeExpansionEvent object.
@@ -71,6 +71,8 @@
/**
* Returns the path to the value that has been expanded/collapsed.
+ *
+ * @return this event's {@code TreePath} object
*/
public TreePath getPath() { return path; }
}
--- a/jdk/src/share/classes/javax/swing/event/TreeExpansionListener.java Fri Jun 20 10:10:27 2014 -0700
+++ b/jdk/src/share/classes/javax/swing/event/TreeExpansionListener.java Mon Jun 23 10:57:22 2014 +0400
@@ -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 @@
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);
}
--- a/jdk/src/share/classes/javax/swing/event/TreeModelListener.java Fri Jun 20 10:10:27 2014 -0700
+++ b/jdk/src/share/classes/javax/swing/event/TreeModelListener.java Mon Jun 23 10:57:22 2014 +0400
@@ -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 @@
* 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.</p>
+ * system.
+ *
* <p>To indicate the root has changed, childIndices and children
- * will be null. </p>
+ * will be null.
*
- * <p>Use <code>e.getPath()</code>
- * to get the parent of the changed node(s).
- * <code>e.getChildIndices()</code>
- * returns the index(es) of the changed node(s).</p>
+ * <p>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);
/**
* <p>Invoked after nodes have been inserted into the tree.</p>
*
- * <p>Use <code>e.getPath()</code>
- * to get the parent of the new node(s).
- * <code>e.getChildIndices()</code>
- * returns the index(es) of the new node(s)
- * in ascending order.</p>
+ * <p>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 @@
* invoked once for the root of the removed subtree, not once for
* each individual set of siblings removed.</p>
*
- * <p>Use <code>e.getPath()</code>
- * to get the former parent of the deleted node(s).
- * <code>e.getChildIndices()</code>
- * returns, in ascending order, the index(es)
- * the node(s) had before being deleted.</p>
+ * <p>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 @@
* one and the first element does not identify the current root node
* the first element should become the new root of the tree.
*
- * <p>Use <code>e.getPath()</code>
- * to get the path to the node.
- * <code>e.getChildIndices()</code>
- * returns null.</p>
+ * <p>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);
--- a/jdk/src/share/classes/javax/swing/event/TreeSelectionEvent.java Fri Jun 20 10:10:27 2014 -0700
+++ b/jdk/src/share/classes/javax/swing/event/TreeSelectionEvent.java Mon Jun 23 10:57:22 2014 +0400
@@ -62,12 +62,16 @@
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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
/**
* Returns the first path element.
+ *
+ * @return the first {@code TreePath} element represented by this event
*/
public TreePath getPath()
{
@@ -187,6 +196,8 @@
/**
* 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 @@
/**
* Returns the current lead path.
+ *
+ * @return a {@code TreePath} containing the new lead selection path
*/
public TreePath getNewLeadSelectionPath() {
return newLeadSelectionPath;
@@ -201,10 +214,14 @@
/**
* 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);
}
--- a/jdk/src/share/classes/javax/swing/event/TreeWillExpandListener.java Fri Jun 20 10:10:27 2014 -0700
+++ b/jdk/src/share/classes/javax/swing/event/TreeWillExpandListener.java Mon Jun 23 10:57:22 2014 +0400
@@ -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 @@
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;
}
--- a/jdk/src/share/classes/javax/swing/event/UndoableEditListener.java Fri Jun 20 10:10:27 2014 -0700
+++ b/jdk/src/share/classes/javax/swing/event/UndoableEditListener.java Mon Jun 23 10:57:22 2014 +0400
@@ -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 @@
/**
* An undoable edit happened
+ *
+ * @param e an {@code UndoableEditEvent} object
*/
void undoableEditHappened(UndoableEditEvent e);
}
--- a/jdk/src/share/classes/javax/swing/tree/ExpandVetoException.java Fri Jun 20 10:10:27 2014 -0700
+++ b/jdk/src/share/classes/javax/swing/tree/ExpandVetoException.java Mon Jun 23 10:57:22 2014 +0400
@@ -28,7 +28,7 @@
import javax.swing.event.TreeExpansionEvent;
/**
- * Exception used to stop and expand/collapse from happening.
+ * Exception used to stop an expand/collapse from happening.
* See <a
href="http://docs.oracle.com/javase/tutorial/uiswing/events/treewillexpandlistener.html">How to Write a Tree-Will-Expand Listener</a>
* in <em>The Java Tutorial</em>