[cp-patches] FYI: More API comments for javax.swing.text

[Roman Kennke]

I added some more comments to javax.swing.text

2005-07-29  Roman Kennke  <address@hidden>

        * javax/swing/text/DefaultStyledDocument.java: Added
        comments all over.
        * javax/swing/text/StyledEditorKit: Likewise.

/Roman

Index: javax/swing/text/DefaultStyledDocument.java
===================================================================
RCS file: 
/cvsroot/classpath/classpath/javax/swing/text/DefaultStyledDocument.java,v
retrieving revision 1.5
diff -u -r1.5 DefaultStyledDocument.java
--- javax/swing/text/DefaultStyledDocument.java 29 Jul 2005 13:01:45 -0000      
1.5
+++ javax/swing/text/DefaultStyledDocument.java 29 Jul 2005 15:26:10 -0000
@@ -45,14 +45,28 @@
 import javax.swing.event.DocumentEvent;
 
 /**
+ * The default implementation of address@hidden StyledDocument}.
+ *
+ * The document is modeled as an address@hidden Element} tree, which has
+ * a address@hidden SecionElement} as single root, which has one or more
+ * address@hidden AbstractDocument.BranchElement}s as paragraph nodes
+ * and each paragraph node having one or more
+ * address@hidden AbstractDocument.LeafElement}s as content nodes.
+ *
  * @author Michael Koch (address@hidden)
+ * @author Roman Kennke (address@hidden)
  */
 public class DefaultStyledDocument extends AbstractDocument
   implements StyledDocument
 {
+  /**
+   * Performs all <em>structural</code> changes to the <code>Element</code>
+   * hierarchy.
+   */
   public class ElementBuffer
     implements Serializable
   {
+    /** The root element of the hierarchy. */
     private Element root;
 
     /** Holds the offset for structural changes. */
@@ -61,11 +75,22 @@
     /** Holds the length of structural changes. */
     private int length;
 
+    /**
+     * Creates a new <code>ElementBuffer</code> for the specified
+     * <code>root</code> element.
+     *
+     * @param root the root element for this <code>ElementBuffer</code>
+     */
     public ElementBuffer(Element root)
     {
       this.root = root;
     }
 
+    /**
+     * Returns the root element of this <code>ElementBuffer</code>.
+     *
+     * @return the root element of this <code>ElementBuffer</code>
+     */
     public Element getRootElement()
     {
       return root;
@@ -147,21 +172,44 @@
                        + "javax.swing.text.AbstractDocument.AbstractElement");
     }
   }
-  
+
+  /**
+   * The default size to use for new content buffers.
+   */
   public static final int BUFFER_SIZE_DEFAULT = 4096;
 
+  /**
+   * The <code>EditorBuffer</code> that is used to manage to
+   * <code>Element</code> hierarchy.
+   */
   protected DefaultStyledDocument.ElementBuffer buffer;
-  
+
+  /**
+   * Creates a new <code>DefaultStyledDocument</code>.
+   */
   public DefaultStyledDocument()
   {
     this(new GapContent(BUFFER_SIZE_DEFAULT), new StyleContext());
   }
 
+  /**
+   * Creates a new <code>DefaultStyledDocument</code> that uses the
+   * specified address@hidden StyleContext}.
+   *
+   * @param context the <code>StyleContext</code> to use
+   */
   public DefaultStyledDocument(StyleContext context)
   {
     this(new GapContent(BUFFER_SIZE_DEFAULT), context);
   }
 
+  /**
+   * Creates a new <code>DefaultStyledDocument</code> that uses the
+   * specified address@hidden StyleContext} and address@hidden Content} buffer.
+   *
+   * @param content the <code>Content</code> buffer to use
+   * @param context the <code>StyleContext</code> to use
+   */
   public DefaultStyledDocument(AbstractDocument.Content content,
                               StyleContext context)
   {
@@ -170,15 +218,38 @@
     setLogicalStyle(0, context.getStyle(StyleContext.DEFAULT_STYLE));
   }
 
+  /**
+   * Adds a style into the style hierarchy. Unspecified style attributes
+   * can be resolved in the <code>parent</code> style, if one is specified.
+   *
+   * While it is legal to add nameless styles (<code>nm == null</code),
+   * you must be aware that the client application is then responsible
+   * for managing the style hierarchy, since unnamed styles cannot be
+   * looked up by their name.
+   *
+   * @param nm the name of the style or <code>null</code> if the style should
+   *           be unnamed
+   * @param parent the parent in which unspecified style attributes are
+   *           resolved, or <code>null</code> if that is not necessary
+   *
+   * @return the newly created <code>Style</code>
+   */
   public Style addStyle(String nm, Style parent)
   {
     StyleContext context = (StyleContext) getAttributeContext();
     return context.addStyle(nm, parent);
   }
-  
+
+  /**
+   * Create the default root element for this kind of <code>Document</code>.
+   *
+   * @return the default root element for this kind of <code>Document</code>
+   */
   protected AbstractDocument.AbstractElement createDefaultRoot()
   {
     Element[] tmp;
+    // FIXME: Create a SecionElement here instead of a BranchElement.
+    // Use createBranchElement() and createLeafElement instead.
     BranchElement section = new BranchElement(null, null);
     
     BranchElement paragraph = new BranchElement(section, null);
@@ -193,7 +264,17 @@
     
     return section;
   }
-  
+
+  /**
+   * Returns the <code>Element</code> that corresponds to the character
+   * at the specified position.
+   *
+   * @param position the position of which we query the corresponding
+   *        <code>Element</code>
+   *
+   * @return the <code>Element</code> that corresponds to the character
+   *         at the specified position
+   */
   public Element getCharacterElement(int position)
   {
     Element element = getDefaultRootElement();
@@ -206,55 +287,118 @@
     
     return element;
   }
-  
+
+  /**
+   * Extracts a background color from a set of attributes.
+   *
+   * @param attributes the attributes from which to get a background color
+   *
+   * @return the background color that correspond to the attributes
+   */
   public Color getBackground(AttributeSet attributes)
   {
     StyleContext context = (StyleContext) getAttributeContext();
     return context.getBackground(attributes);
   }
-  
+
+  /**
+   * Returns the default root element.
+   *
+   * @return the default root element
+   */
   public Element getDefaultRootElement()
   {
     return buffer.getRootElement();
   }
-  
+
+  /**
+   * Extracts a font from a set of attributes.
+   *
+   * @param attributes the attributes from which to get a font
+   *
+   * @return the font that correspond to the attributes
+   */
   public Font getFont(AttributeSet attributes)
   {
     StyleContext context = (StyleContext) getAttributeContext();
     return context.getFont(attributes);
   }
   
+  /**
+   * Extracts a foreground color from a set of attributes.
+   *
+   * @param attributes the attributes from which to get a foreground color
+   *
+   * @return the foreground color that correspond to the attributes
+   */
   public Color getForeground(AttributeSet attributes)
   {
     StyleContext context = (StyleContext) getAttributeContext();
     return context.getForeground(attributes);
   }
-  
+
+  /**
+   * Returns the logical <code>Style</code> for the specified position.
+   *
+   * @param position the position from which to query to logical style
+   *
+   * @return the logical <code>Style</code> for the specified position
+   */
   public Style getLogicalStyle(int position)
   {
     Element paragraph = getParagraphElement(position);
     AttributeSet attributes = paragraph.getAttributes();
     return (Style) attributes.getResolveParent();
   }
-  
+
+  /**
+   * Returns the paragraph element for the specified position.
+   *
+   * @param position the position for which to query the paragraph element
+   *
+   * @return the paragraph element for the specified position
+   */
   public Element getParagraphElement(int position)
   {
     Element element = getCharacterElement(position);
     return element.getParentElement();
   }
 
+  /**
+   * Looks up and returns a named <code>Style</code>.
+   *
+   * @param nm the name of the <code>Style</code>
+   *
+   * @return the found <code>Style</code> of <code>null</code> if no such
+   *         <code>Style</code> exists
+   */
   public Style getStyle(String nm)
   {
     StyleContext context = (StyleContext) getAttributeContext();
     return context.getStyle(nm);
   }
 
+  /**
+   * Removes a named <code>Style</code> from the style hierarchy.
+   *
+   * @param nm the name of the <code>Style</code> to be removed
+   */
   public void removeStyle(String nm)
   {
     StyleContext context = (StyleContext) getAttributeContext();
     context.removeStyle(nm);
   }
 
+  /**
+   * Sets text attributes for the fragment specified by <code>offset</code>
+   * and <code>length</code>.
+   *
+   * @param offset the start offset of the fragment
+   * @param length the length of the fragment
+   * @param attribute the text attributes to set
+   * @param replace if <code>true</code>, the attributes of the current
+   *     selection are overridden, otherwise they are merged
+   */
   public void setCharacterAttributes(int offset, int length,
                                     AttributeSet attributes,
                                     boolean replace)
@@ -303,6 +447,12 @@
       }
   }
   
+  /**
+   * Sets the logical style for the paragraph at the specified position.
+   *
+   * @param position the position at which the logical style is added
+   * @param style the style to set for the current paragraph
+   */
   public void setLogicalStyle(int position, Style style)
   {
     Element el = getParagraphElement(position);
@@ -316,6 +466,15 @@
          + "instances of javax.swing.text.AbstractDocument.AbstractElement");
   }
 
+  /**
+   * Sets text attributes for the paragraph at the specified fragment.
+   *
+   * @param offset the beginning of the fragment
+   * @param length the length of the fragment
+   * @param attribute the text attributes to set
+   * @param replace if <code>true</code>, the attributes of the current
+   *     selection are overridden, otherwise they are merged
+   */
   public void setParagraphAttributes(int offset, int length,
                                     AttributeSet attributes,
                                     boolean replace)
Index: javax/swing/text/StyledEditorKit.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/text/StyledEditorKit.java,v
retrieving revision 1.10
diff -u -r1.10 StyledEditorKit.java
--- javax/swing/text/StyledEditorKit.java       29 Jul 2005 13:01:46 -0000      
1.10
+++ javax/swing/text/StyledEditorKit.java       29 Jul 2005 15:26:10 -0000
@@ -51,21 +51,23 @@
 import javax.swing.event.CaretListener;
 
 /**
- * StyledEditorKit
+ * An address@hidden EditorKit} that supports editing styled text.
  *
  * @author Andrew Selkirk
+ * @author Roman Kennke (address@hidden)
  */
 public class StyledEditorKit extends DefaultEditorKit
 {
+  /** The serialVersionUID. */
   private static final long serialVersionUID = 7002391892985555948L;
 
   /**
-   * UnderlineAction
+   * Toggles the underline attribute for the selected text.
    */
   public static class UnderlineAction extends StyledEditorKit.StyledTextAction
   {
     /**
-     * Constructor UnderlineAction
+     * Creates an instance of <code>UnderlineAction</code>.
      */
     public UnderlineAction()
     {
@@ -73,8 +75,9 @@
     }
 
     /**
-     * actionPerformed
-     * @param event TODO
+     * Performs the action.
+     *
+     * @param event the <code>ActionEvent</code> that describes the action
      */
     public void actionPerformed(ActionEvent event)
     {
@@ -89,12 +92,12 @@
   }
 
   /**
-   * ItalicAction
+   * Toggles the italic attribute for the selected text.
    */
   public static class ItalicAction extends StyledEditorKit.StyledTextAction
   {
     /**
-     * Constructor ItalicAction
+     * Creates an instance of <code>ItalicAction</code>.
      */
     public ItalicAction()
     {
@@ -102,8 +105,9 @@
     }
 
     /**
-     * actionPerformed
-     * @param event TODO
+     * Performs the action.
+     *
+     * @param event the <code>ActionEvent</code> that describes the action
      */
     public void actionPerformed(ActionEvent event)
     {
@@ -118,12 +122,12 @@
   }
 
   /**
-   * BoldAction
+   * Toggles the bold attribute for the selected text.
    */
   public static class BoldAction extends StyledEditorKit.StyledTextAction
   {
     /**
-     * Constructor BoldAction
+     * Creates an instance of <code>BoldAction</code>.
      */
     public BoldAction()
     {
@@ -131,8 +135,9 @@
     }
 
     /**
-     * actionPerformed
-     * @param event TODO
+     * Performs the action.
+     *
+     * @param event the <code>ActionEvent</code> that describes the action
      */
     public void actionPerformed(ActionEvent event)
     {
@@ -147,19 +152,21 @@
   }
 
   /**
-   * AlignmentAction
+   * Sets the alignment attribute on the selected text.
    */
   public static class AlignmentAction extends StyledEditorKit.StyledTextAction
   {
     /**
-     * a
+     * The aligment to set.
      */
     private int a;
 
     /**
-     * Constructor AlignmentAction
-     * @param nm TODO
-     * @param a TODO
+     * Creates a new instance of <code>AlignmentAction</code> to set the
+     * alignment to <code>a</code>.
+     *
+     * @param nm the name of the Action
+     * @param a the alignment to set
      */
     public AlignmentAction(String nm, int a)
     {
@@ -168,8 +175,9 @@
     }
 
     /**
-     * actionPerformed
-     * @param event TODO
+     * Performs the action.
+     *
+     * @param event the <code>ActionEvent</code> that describes the action
      */
     public void actionPerformed(ActionEvent event)
     {
@@ -180,19 +188,21 @@
   }
 
   /**
-   * ForegroundAction
+   * Sets the foreground color attribute on the selected text.
    */
   public static class ForegroundAction extends StyledEditorKit.StyledTextAction
   {
     /**
-     * fg
+     * The foreground color to set.
      */
     private Color fg;
 
     /**
-     * Constructor ForegroundAction
-     * @param nm TODO
-     * @param fg TODO
+     * Creates a new instance of <code>ForegroundAction</code> to set the
+     * foreground color to <code>fg</code>.
+     *
+     * @param nm the name of the Action
+     * @param fg the foreground color to set
      */
     public ForegroundAction(String nm, Color fg)
     {
@@ -201,8 +211,9 @@
     }
 
     /**
-     * actionPerformed
-     * @param event TODO
+     * Performs the action.
+     *
+     * @param event the <code>ActionEvent</code> that describes the action
      */
     public void actionPerformed(ActionEvent event)
     {
@@ -213,19 +224,21 @@
   }
 
   /**
-   * FontSizeAction
+   * Sets the font size attribute on the selected text.
    */
   public static class FontSizeAction extends StyledEditorKit.StyledTextAction
   {
     /**
-     * size
+     * The font size to set.
      */
     private int size;
 
     /**
-     * Constructor FontSizeAction
-     * @param nm TODO
-     * @param size TODO
+     * Creates a new instance of <code>FontSizeAction</code> to set the
+     * font size to <code>size</code>.
+     *
+     * @param nm the name of the Action
+     * @param size the font size to set
      */
     public FontSizeAction(String nm, int size)
     {
@@ -234,8 +247,9 @@
     }
 
     /**
-     * actionPerformed
-     * @param event TODO
+     * Performs the action.
+     *
+     * @param event the <code>ActionEvent</code> that describes the action
      */
     public void actionPerformed(ActionEvent event)
     {
@@ -246,19 +260,21 @@
   }
 
   /**
-   * FontFamilyAction
+   * Sets the font family attribute on the selected text.
    */
   public static class FontFamilyAction extends StyledEditorKit.StyledTextAction
   {
     /**
-     * family
+     * The font family to set.
      */
     private String family;
 
     /**
-     * Constructor FontFamilyAction
-     * @param nm TODO
-     * @param family TODO
+     * Creates a new instance of <code>FontFamilyAction</code> to set the
+     * font family to <code>family</code>.
+     *
+     * @param nm the name of the Action
+     * @param family the font family to set
      */
     public FontFamilyAction(String nm, String family)
     {
@@ -267,8 +283,9 @@
     }
 
     /**
-     * actionPerformed
-     * @param event TODO
+     * Performs the action.
+     *
+     * @param event the <code>ActionEvent</code> that describes the action
      */
     public void actionPerformed(ActionEvent event)
     {
@@ -279,13 +296,15 @@
   }
 
   /**
-   * StyledTextAction
+   * The abstract superclass of all styled TextActions. This class
+   * provides some useful methods to manipulate the text attributes.
    */
   public abstract static class StyledTextAction extends TextAction
   {
     /**
-     * Constructor StyledTextAction
-     * @param nm TODO
+     * Creates a new instance of <code>StyledTextAction</code>.
+     *
+     * @param nm the name of the <code>StyledTextAction</code>
      */
     public StyledTextAction(String nm)
     {
@@ -293,9 +312,12 @@
     }
 
     /**
-     * getEditor
-     * @param event TODO
-     * @returns JEditorPane
+     * Returns the <code>JEditorPane</code> component from which the
+     * <code>ActionEvent</code> originated.
+     *
+     * @param event the <code>ActionEvent</code>
+     * @return the <code>JEditorPane</code> component from which the
+     *         <code>ActionEvent</code> originated
      */
     protected final JEditorPane getEditor(ActionEvent event)
     {
@@ -303,10 +325,15 @@
     }
 
     /**
-     * setCharacterAttributes
-     * @param value0 TODO
-     * @param value1 TODO
-     * @param value2 TODO
+     * Sets the specified character attributes on the currently selected
+     * text of <code>editor</code>. If <code>editor</code> does not have
+     * a selection, then the attributes are used as input attributes
+     * for newly inserted content.
+     *
+     * @param editor the <code>JEditorPane</code> component
+     * @param atts the text attributes to set
+     * @param replace if <code>true</code> the current attributes of the
+     *        selection are replaces, otherwise they are merged
      */
     protected final void setCharacterAttributes(JEditorPane editor,
                                                 AttributeSet atts,
@@ -344,9 +371,12 @@
     }
 
     /**
-     * getStyledDocument
-     * @param value0 TODO
-     * @returns StyledDocument
+     * Returns the address@hidden StyledDocument} that is used by 
<code>editor</code>.
+     *
+     * @param editor the <code>JEditorPane</code> from which to get the
+     *        <code>StyledDocument</code>
+     *
+     * @return the address@hidden StyledDocument} that is used by 
<code>editor</code>
      */
     protected final StyledDocument getStyledDocument(JEditorPane editor)
     {
@@ -359,9 +389,12 @@
     }
 
     /**
-     * getStyledEditorKit
-     * @param value0 TODO
-     * @returns StyledEditorKit
+     * Returns the address@hidden StyledEditorKit} that is used by 
<code>editor</code>.
+     *
+     * @param editor the <code>JEditorPane</code> from which to get the
+     *        <code>StyledEditorKit</code>
+     *
+     * @return the address@hidden StyledEditorKit} that is used by 
<code>editor</code>
      */
     protected final StyledEditorKit getStyledEditorKit(JEditorPane editor)
     {
@@ -374,10 +407,16 @@
     }
 
     /**
-     * setParagraphAttributes
-     * @param value0 TODO
-     * @param value1 TODO
-     * @param value2 TODO
+     * Sets the specified character attributes on the paragraph that
+     * contains the currently selected
+     * text of <code>editor</code>. If <code>editor</code> does not have
+     * a selection, then the attributes are set on the paragraph that
+     * contains the current caret position.
+     *
+     * @param editor the <code>JEditorPane</code> component
+     * @param atts the text attributes to set
+     * @param replace if <code>true</code> the current attributes of the
+     *        selection are replaces, otherwise they are merged
      */
     protected final void setParagraphAttributes(JEditorPane editor,
                                                 AttributeSet atts,