[cp-patches] FYI: API doc updates for AbstractTableModel and DefaultTableModel

[David Gilbert]

I committed the following change to update/fix the API docs for two classes:

2005-06-28  David Gilbert  <address@hidden>

        * javax/swing/table/AbstractTableModel.java: updated API docs,
        * javax/swing/table/DefaultTableModel.java: fixed API docs.

Regards,

Dave Gilbert

Index: javax/swing/table/AbstractTableModel.java
===================================================================
RCS file: 
/cvsroot/classpath/classpath/javax/swing/table/AbstractTableModel.java,v
retrieving revision 1.12
diff -u -r1.12 AbstractTableModel.java
--- javax/swing/table/AbstractTableModel.java   24 Jun 2005 21:06:28 -0000      
1.12
+++ javax/swing/table/AbstractTableModel.java   28 Jun 2005 11:28:23 -0000
@@ -1,5 +1,5 @@
 /* AbstractTableModel.java --
-   Copyright (C) 2002, 2004  Free Software Foundation, Inc.
+   Copyright (C) 2002, 2004, 2005  Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -46,7 +46,8 @@
 import javax.swing.event.TableModelListener;
 
 /**
- * AbstractTableModel
+ * A base class that can be used to create implementations of the 
+ * address@hidden TableModel} interface.
  * 
  * @author Andrew Selkirk
  */
@@ -55,52 +56,58 @@
   static final long serialVersionUID = -5798593159423650347L;
 
   /**
-   * listenerList
+   * Storage for the listeners registered with this model.
    */
   protected EventListenerList listenerList = new EventListenerList();
 
   /**
-   * Constructor AbstractTableModel
+   * Creates a default instance.
    */
   public AbstractTableModel()
   {
-    // TODO
+    // no setup required here
   }
 
   /**
-   * Get the name of the column for this index. If you do not override
-   * this methode, you'll get something like: 0, A; 1, B; ...; AA; AB;
-   * ...
+   * Returns the name of the specified column.  This method generates default 
+   * names in a sequence (starting with column 0):  A, B, C, ..., Z, AA, AB, 
+   * AC, ..., AZ, BA, BB, BC, and so on.  Subclasses may override this method
+   * to allow column names to be specified on some other basis. 
    *
-   * @param columnIndex The index of the column.
+   * @param columnIndex  the column index.
    *
    * @return The name of the column.
    */
-  public String getColumnName (int columnIndex)
+  public String getColumnName(int columnIndex)
   {
     StringBuffer buffer = new StringBuffer();
     while (columnIndex >= 0)
       {
-       buffer.insert (0, (char) ('A' + columnIndex % 26));
-       columnIndex = columnIndex / 26 - 1;
+        buffer.insert (0, (char) ('A' + columnIndex % 26));
+        columnIndex = columnIndex / 26 - 1;
       }
     return buffer.toString();
   }
 
   /**
-   * Return the index of the given name.
+   * Return the index of the specified column, or <code>-1</code> if there is
+   * no column with the specified name.
    *
-   * @param columnName The name of the column.
+   * @param columnName  the name of the column (<code>null</code> not 
permitted).
    *
    * @return The index of the column, -1 if not found.
+   * 
+   * @see #getColumnName(int)
+   * @throws NullPointerException if <code>columnName</code> is 
+   *         <code>null</code>.
    */
-  public int findColumn (String columnName)
+  public int findColumn(String columnName)
   {
     int count = getColumnCount();
     
     for (int index = 0; index < count; index++)
       {
-        String name = getColumnName (index);
+        String name = getColumnName(index);
         
         if (columnName.equals(name))
           return index;
@@ -111,77 +118,87 @@
   }
 
   /**
-   * Returns the class of a comlumn.
-   *
-   * @param columnIndex The index of the column.
-   *
-   * @return The class type of the column.
+   * Returns the <code>Class</code> for all <code>Object</code> instances
+   * in the specified column.  
+   * 
+   * @param columnIndex the column index.
+   * 
+   * @return The class.
    */
-  public Class getColumnClass (int columnIndex)
+  public Class getColumnClass(int columnIndex)
   {
     return Object.class;
   }
 
   /**
-   * Tells whether a cell is editable.
+   * Returns <code>true</code> if the specified cell is editable, and 
+   * <code>false</code> if it is not.  This implementation returns 
+   * <code>false</code> for all arguments, subclasses should override the 
+   * method if necessary.
    *
-   * @param rowIndex The row of the cell.
-   * @param columnIndex The index of the cell.
+   * @param rowIndex  the row index of the cell.
+   * @param columnIndex  the column index of the cell.
    *
-   * @return True if cell is editable.
+   * @return <code>false</code>.
    */
-  public boolean isCellEditable (int rowIndex, int columnIndex)
+  public boolean isCellEditable(int rowIndex, int columnIndex)
   {
     return false;
   }
 
   /**
-   * Sets a cell to a value.
-   *
-   * @param value New value of cell.
-   * @param rowIndex The row of the cell.
-   * @param columnIndex The column of the cell.
+   * Sets the value of the given cell.  This implementation ignores all 
+   * arguments and does nothing, subclasses should override the 
+   * method if necessary.
+   *
+   * @param value  the new value (<code>null</code> permitted).
+   * @param rowIndex  the row index of the cell.
+   * @param columnIndex  the column index of the cell.
    */
-  public void setValueAt (Object value, int rowIndex, int columnIndex)
+  public void setValueAt(Object value, int rowIndex, int columnIndex)
   {
     // Do nothing...
   }
 
   /**
-   * Add a TableModelListener.
+   * Adds a listener to the table model.  The listener will receive 
notification
+   * of all changes to the table model.
    *
-   * @param listener The listener to add.
+   * @param listener  the listener.
    */
-  public void addTableModelListener (TableModelListener listener)
+  public void addTableModelListener(TableModelListener listener)
   {
-    listenerList.add (TableModelListener.class, listener);
+    listenerList.add(TableModelListener.class, listener);
   }
 
   /**
-   * Removes a TableModelListener.
+   * Removes a listener from the table model so that it will no longer receive
+   * notification of changes to the table model.
    *
-   * @param listener The listener to remove.
+   * @param listener  the listener to remove.
    */
-  public void removeTableModelListener (TableModelListener listener)
+  public void removeTableModelListener(TableModelListener listener)
   {
-    listenerList.remove (TableModelListener.class, listener);
+    listenerList.remove(TableModelListener.class, listener);
   }
 
   /**
-   * Return all registered TableModelListener objects.
+   * Returns an array containing the listeners that have been added to the
+   * table model.
    *
-   * @return Array of TableModelListener objects.
+   * @return Array of address@hidden TableModelListener} objects.
    *
    * @since 1.4
    */
   public TableModelListener[] getTableModelListeners()
   {
     return (TableModelListener[])
-      listenerList.getListeners (TableModelListener.class);
+      listenerList.getListeners(TableModelListener.class);
   }
 
   /**
-   * fireTableDataChanged
+   * Sends a address@hidden TableModelEvent} to all registered listeners to 
inform
+   * them that the table data has changed.
    */
   public void fireTableDataChanged()
   {
@@ -189,64 +206,74 @@
   }
 
   /**
-   * fireTableStructureChanged
+   * Sends a address@hidden TableModelEvent} to all registered listeners to 
inform
+   * them that the table structure has changed.
    */
   public void fireTableStructureChanged()
   {
-    fireTableChanged (new TableModelEvent (this, TableModelEvent.HEADER_ROW));
+    fireTableChanged(new TableModelEvent(this, TableModelEvent.HEADER_ROW));
   }
 
   /**
-   * fireTableRowsInserted
-   * @param value0 TODO
-   * @param value1 TODO
+   * Sends a address@hidden TableModelEvent} to all registered listeners to 
inform
+   * them that some rows have been inserted into the model.
+   * 
+   * @param firstRow  the index of the first row.
+   * @param lastRow  the index of the last row.
    */
   public void fireTableRowsInserted (int firstRow, int lastRow)
   {
-    fireTableChanged (new TableModelEvent (this, firstRow, lastRow,
-                                           TableModelEvent.ALL_COLUMNS,
-                                           TableModelEvent.INSERT));
+    fireTableChanged(new TableModelEvent(this, firstRow, lastRow,
+                                         TableModelEvent.ALL_COLUMNS,
+                                         TableModelEvent.INSERT));
   }
 
   /**
-   * fireTableRowsUpdated
-   * @param value0 TODO
-   * @param value1 TODO
+   * Sends a address@hidden TableModelEvent} to all registered listeners to 
inform
+   * them that some rows have been updated.
+   * 
+   * @param firstRow  the index of the first row.
+   * @param lastRow  the index of the last row.
    */
   public void fireTableRowsUpdated (int firstRow, int lastRow)
   {
-    fireTableChanged (new TableModelEvent (this, firstRow, lastRow,
-                                           TableModelEvent.ALL_COLUMNS,
-                                           TableModelEvent.UPDATE));
+    fireTableChanged(new TableModelEvent(this, firstRow, lastRow,
+                                         TableModelEvent.ALL_COLUMNS,
+                                         TableModelEvent.UPDATE));
   }
 
   /**
-   * fireTableRowsDeleted
-   * @param value0 TODO
-   * @param value1 TODO
+   * Sends a address@hidden TableModelEvent} to all registered listeners to 
inform
+   * them that some rows have been deleted from the model.
+   * 
+   * @param firstRow  the index of the first row.
+   * @param lastRow  the index of the last row.
    */
   public void fireTableRowsDeleted(int firstRow, int lastRow)
   {
-    fireTableChanged (new TableModelEvent (this, firstRow, lastRow,
-                                           TableModelEvent.ALL_COLUMNS,
-                                           TableModelEvent.DELETE));
+    fireTableChanged(new TableModelEvent(this, firstRow, lastRow,
+                                         TableModelEvent.ALL_COLUMNS,
+                                         TableModelEvent.DELETE));
   }
 
   /**
-   * fireTableCellUpdated
-   * @param value0 TODO
-   * @param value1 TODO
+   * Sends a address@hidden TableModelEvent} to all registered listeners to 
inform
+   * them that a single cell has been updated.
+   * 
+   * @param row  the row index.
+   * @param column  the column index.
    */
   public void fireTableCellUpdated (int row, int column)
   {
-    fireTableChanged (new TableModelEvent (this, row, row, column));
+    fireTableChanged(new TableModelEvent(this, row, row, column));
   }
 
   /**
-   * fireTableChanged
-   * @param value0 TODO
+   * Sends the specified event to all registered listeners.
+   * 
+   * @param event  the event to send.
    */
-  public void fireTableChanged (TableModelEvent event)
+  public void fireTableChanged(TableModelEvent event)
   {
     int        index;
     TableModelListener listener;
@@ -260,12 +287,15 @@
   }
 
   /**
-   * getListeners
-   * @param value0 TODO
-   * @return EventListener[]
+   * Returns an array of listeners of the given type that are registered with
+   * this model.
+   * 
+   * @param listenerType  the listener class.
+   * 
+   * @return An array of listeners (possibly empty).
    */
-  public EventListener[] getListeners (Class listenerType)
+  public EventListener[] getListeners(Class listenerType)
   {
-    return listenerList.getListeners (listenerType);
+    return listenerList.getListeners(listenerType);
   }
 }
Index: javax/swing/table/DefaultTableModel.java
===================================================================
RCS file: 
/cvsroot/classpath/classpath/javax/swing/table/DefaultTableModel.java,v
retrieving revision 1.11
diff -u -r1.11 DefaultTableModel.java
--- javax/swing/table/DefaultTableModel.java    24 Jun 2005 21:06:29 -0000      
1.11
+++ javax/swing/table/DefaultTableModel.java    28 Jun 2005 11:28:23 -0000
@@ -61,7 +61,7 @@
   protected Vector dataVector;
 
   /**
-   * columnIdentifiers
+   * Storage for the column identifiers.
    */
   protected Vector columnIdentifiers;
 
@@ -160,7 +160,7 @@
   /**
    * Returns the vector containing the row data for the table.
    * 
-   * @returns The data vector.
+   * @return The data vector.
    */
   public Vector getDataVector() 
   {
@@ -281,7 +281,7 @@
    * If <code>rowCount</code> is greater than the current number of rows in
    * the table, new (empty) rows are added.
    * 
-   * @param the row count.
+   * @param rowCount the row count.
    */
   public void setRowCount(int rowCount) 
   {
@@ -468,8 +468,9 @@
   }
 
   /**
-   * getRowCount
-   * @returns int
+   * Returns the number of rows in the model.
+   * 
+   * @return The row count.
    */
   public int getRowCount() {
     return dataVector.size();
@@ -489,7 +490,7 @@
    * 
    * @param column the column index.
    * 
-   * @returns The column name.
+   * @return The column name.
    */
   public String getColumnName(int column) {
     String result = "";
@@ -519,7 +520,7 @@
    * @param row the row index.
    * @param column the column index.
    * 
-   * @returns <code>true</code> in all cases.
+   * @return <code>true</code> in all cases.
    */
   public boolean isCellEditable(int row, int column) {
     return true;
@@ -531,8 +532,8 @@
    * @param row the row index.
    * @param column the column index.
    * 
-   * @returns The value (<code>Object</code>, possibly <code>null</code>) at 
-   *          the specified cell in the table.
+   * @return The value (<code>Object</code>, possibly <code>null</code>) at 
+   *         the specified cell in the table.
    */
   public Object getValueAt(int row, int column) {
     return ((Vector) dataVector.get(row)).get(column);
@@ -556,8 +557,8 @@
    * 
    * @param data the data array (<code>null</code> permitted).
    * 
-   * @returns A vector (or <code>null</code> if the data array 
-   *          is <code>null</code>).
+   * @return A vector (or <code>null</code> if the data array 
+   *         is <code>null</code>).
    */
   protected static Vector convertToVector(Object[] data) {
     if (data == null)
@@ -571,10 +572,10 @@
   /**
    * Converts the data array to a <code>Vector</code> of rows.
    * 
-   * @param the data array (<code>null</code> permitted).
+   * @param data the data array (<code>null</code> permitted).
    * 
-   * @returns A vector (or <code>null</code> if the data array 
-   *          is <code>null</code>.
+   * @return A vector (or <code>null</code> if the data array 
+   *         is <code>null</code>.
    */
   protected static Vector convertToVector(Object[][] data) {
     if (data == null)