[cp-patches] FYI: Added API comments to javax.swing.text classes

[Roman Kennke]

2005-08-03  Roman Kennke  <address@hidden>

        * javax/swing/text/AttributeSet.java: Added some API comments
        to class description.
        * javax/swing/text/BadLocationException.java: Added / fixed
        API comments all over.
        * javax/swing/text/Caret.java: Added API comments all over.


/Roman

Index: javax/swing/text/AttributeSet.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/text/AttributeSet.java,v
retrieving revision 1.10
diff -u -r1.10 AttributeSet.java
--- javax/swing/text/AttributeSet.java  1 Aug 2005 20:44:49 -0000       1.10
+++ javax/swing/text/AttributeSet.java  3 Aug 2005 08:51:10 -0000
@@ -1,5 +1,5 @@
 /* AttributeSet.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.
 
@@ -42,9 +42,14 @@
 /**
  * A set of attributes. An attribute has a key and a value. They typically
  * describe features of a piece of text that make up its graphical
- * representation
+ * representation.
+ *
+ * An <code>AttributeSet</code> may have a resolving parent,
+ * that is another <code>AttributeSet</code> that is searched for attribute
+ * keys that are not stored locally in this <code>AttributeSet</code>.
  *
  * @author original author unknown
+ * @author Roman Kennke (address@hidden)
  */
 public interface AttributeSet
 { 
Index: javax/swing/text/BadLocationException.java
===================================================================
RCS file: 
/cvsroot/classpath/classpath/javax/swing/text/BadLocationException.java,v
retrieving revision 1.5
diff -u -r1.5 BadLocationException.java
--- javax/swing/text/BadLocationException.java  2 Jul 2005 20:32:51 -0000       
1.5
+++ javax/swing/text/BadLocationException.java  3 Aug 2005 08:51:10 -0000
@@ -1,5 +1,5 @@
 /* BadLocationException.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.
 
@@ -37,17 +37,28 @@
 
 package javax.swing.text;
 
+/**
+ * Indicates that an invalid location within a <code>Document</code> has been
+ * accessed.
+ *
+ * @author original author unknown
+ * @author Roman Kennke (address@hidden)
+ */
 public class BadLocationException extends Exception
 {
+  /** The serial version UID for BadLocationException. */
   private static final long serialVersionUID = -7712259886815656766L;
-  
+
+  /**
+   * The invalid location.
+   */
   int offset;
 
   /**
    * Constructs a <code>BadLocationException</code>
    *
-   * @param str A string indicating what was wrong with the arguments
-   * @param offset Offset within the document that was requested &gt;= 0
+   * @param str a string indicating what was wrong with the arguments
+   * @param offset offset within the document that was requested &gt;= 0
    */
   public BadLocationException(String str, int offset)
   {
@@ -56,7 +67,9 @@
   }
 
   /**
-   * Returns the offset into the document that was not legal
+   * Returns the offset into the document that was not legal.
+   *
+   * @return the offset into the document that was not legal
    */
   public int offsetRequested()
   {
Index: javax/swing/text/Caret.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/text/Caret.java,v
retrieving revision 1.7
diff -u -r1.7 Caret.java
--- javax/swing/text/Caret.java 2 Jul 2005 20:32:51 -0000       1.7
+++ javax/swing/text/Caret.java 3 Aug 2005 08:51:10 -0000
@@ -1,5 +1,5 @@
 /* Caret.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.
 
@@ -43,39 +43,165 @@
 
 import javax.swing.event.ChangeListener;
 
+/**
+ * Defines the method to be implemented by a caret that can be used in Swing
+ * text components.
+ *
+ * @author original author unknown
+ * @author Roman Kennke (address@hidden)
+ */
 public interface Caret
 {
+  /**
+   * Registers a address@hidden ChangeListener} that is notified whenever that 
state
+   * of this <code>Caret</code> changes.
+   *
+   * @param l the listener to register to this caret
+   */
   void addChangeListener(ChangeListener l);
+
+  /**
+   * Removes a address@hidden ChangeListener} from the list of registered 
listeners.
+   *
+   * @param l the listener to remove
+   */
+  void removeChangeListener(ChangeListener l);
+
+  /**
+   * Installs this <code>Caret</code> on the specified text component. This
+   * usually involves setting up listeners.
+   *
+   * This method is called by address@hidden JTextComponent#setCaret(Caret)} 
after
+   * this caret has been set on the text component.
+   *
+   * @param c the text component to install this caret to
+   */
+  void install(JTextComponent c);
   
+  /**
+   * Deinstalls this <code>Caret</code> from the specified text component.
+   * This usually involves removing listeners from the text component.
+   *
+   * This method is called by address@hidden JTextComponent#setCaret(Caret)} 
before
+   * this caret is removed from the text component.
+   *
+   * @param c the text component to deinstall this caret from
+   */
   void deinstall(JTextComponent c);
-  
+
+  /**
+   * Returns the blink rate of this <code>Caret</code> in milliseconds.
+   * A value of <code>0</code> means that the caret does not blink.
+   *
+   * @return the blink rate of this <code>Caret</code> or <code>0</code> if
+   *         this caret does not blink
+   */
   int getBlinkRate();
+
+  /**
+   * Sets the blink rate of this <code>Caret</code> in milliseconds.
+   * A value of <code>0</code> means that the caret does not blink.
+   *
+   * @param rate the new blink rate to set
+   */
+  void setBlinkRate(int rate);
   
+  /**
+   * Returns the current position of this <code>Caret</code> within the
+   * <code>Document</code>.
+   *
+   * @return the current position of this <code>Caret</code> within the
+   *         <code>Document</code>
+   */
   int getDot();
+
+  /**
+   * Sets the current position of this <code>Caret</code> within the
+   * <code>Document</code>. This also sets the <code>mark</code> to the
+   * new location.
+   *
+   * @param dot the new position to be set
+   *
+   * @see address@hidden #moveDot(int)}
+   */
+  void setDot(int dot);
   
-  Point getMagicCaretPosition();
-  
-  int getMark();
-  
-  void install(JTextComponent c);
-  
-  boolean isSelectionVisible();
-  
-  boolean isVisible();
-  
+  /**
+   * Moves the <code>dot</code> location without touching the
+   * <code>mark</code>. This is used when making a selection.
+   *
+   * @param dot the location where to move the dot
+   *
+   * @see address@hidden #setDot(int)}
+   */
   void moveDot(int dot);
   
-  void paint(Graphics g);
-  
-  void removeChangeListener(ChangeListener l);
-  
-  void setBlinkRate(int rate);
-  
-  void setDot(int dot);
+  /**
+   * Returns the current position of the <code>mark</code>. The
+   * <code>mark</code> marks the location in the <code>Document</code> that
+   * is the end of a selection. If there is no selection, the <code>mark</code>
+   * is the same as the <code>dot</code>.
+   *
+   * @return the current position of the mark
+   */
+  int getMark();
   
+  /**
+   * Returns the current visual position of this <code>Caret</code>.
+   *
+   * @return the current visual position of this <code>Caret</code>
+   *
+   * @see address@hidden #setMagicCaretPosition}
+   */
+  Point getMagicCaretPosition();
+
+  /**
+   * Sets the current visual position of this <code>Caret</code>.
+   *
+   * @param p the Point to use for the saved location. May be <code>null</code>
+   *        to indicate that there is no visual location
+   */
   void setMagicCaretPosition(Point p);
-  
+
+  /**
+   * Returns <code>true</code> if the selection is currently visible,
+   * <code>false</code> otherwise.
+   *
+   * @return <code>true</code> if the selection is currently visible,
+   *         <code>false</code> otherwise
+   */
+  boolean isSelectionVisible();
+
+  /**
+   * Sets the visiblity state of the selection.
+   *
+   * @param v <code>true</code> if the selection should be visible,
+   *        <code>false</code> otherwise
+   */
   void setSelectionVisible(boolean v);
-  
+
+  /**
+   * Returns <code>true</code> if this <code>Caret</code> is currently visible,
+   * and <code>false</code> if it is not.
+   *
+   * @return <code>true</code> if this <code>Caret</code> is currently visible,
+   *         and <code>false</code> if it is not
+   */
+  boolean isVisible();
+
+  /**
+   * Sets the visibility state of the caret. <code>true</code> shows the
+   * <code>Caret</code>, <code>false</code> hides it.
+   *
+   * @param v the visibility to set
+   */  
   void setVisible(boolean v);
+
+  /**
+   * Paints this <code>Caret</code> to the specified <code>Graphics</code>
+   * context.
+   *
+   * @param g the graphics context to render to
+   */
+  void paint(Graphics g);  
 }