[cp-patches] FYI: Added API comments to StyledEditorKit

[Roman Kennke]

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

        * javax/swing/text/StyledEditorKit.java: Added the remaining API
        comments.

/Roman

Index: javax/swing/text/StyledEditorKit.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/text/StyledEditorKit.java,v
retrieving revision 1.11
diff -u -r1.11 StyledEditorKit.java
--- javax/swing/text/StyledEditorKit.java       29 Jul 2005 15:27:41 -0000      
1.11
+++ javax/swing/text/StyledEditorKit.java       29 Jul 2005 23:00:18 -0000
@@ -455,15 +455,29 @@
   }
 
   /**
-   * StyledViewFactory
+   * A address@hidden ViewFactory} that is able to create address@hidden 
View}s for
+   * the <code>Element</code>s that are supported by
+   * <code>StyledEditorKit</code>, namely the following types of Elements:
+   *
+   * <ul>
+   * <li>address@hidden AbstractDocument.ContentElementName}</li>
+   * <li>address@hidden AbstractDocument.ParagraphElementName}</li>
+   * <li>address@hidden AbstractDocument.SectionElementName}</li>
+   * <li>address@hidden StyleContext.ComponentElementName}</li>
+   * <li>address@hidden StyleContext.IconElementName}</li>
+   * </ul>
    */
   static class StyledViewFactory
     implements ViewFactory
   {
     /**
-     * create
-     * @param value0 TODO
-     * @returns View
+     * Creates a address@hidden View} for the specified <code>Element</code>.
+     *
+     * @param element the <code>Element</code> to create a <code>View</code>
+     *        for
+     * @return the <code>View</code> for the specified <code>Element</code>
+     *         or <code>null</code> if the type of <code>element</code> is
+     *         not supported
      */
     public View create(Element element)
     {
@@ -485,14 +499,16 @@
   }
 
   /**
-   * AttributeTracker
+   * Keeps track of the caret position and updates the currentRun
+   * <code>Element</code> and the <code>inputAttributes</code>.
    */
   class CaretTracker
     implements CaretListener
   {
     /**
-     * caretUpdate
-     * @param value0 TODO
+     * Notifies an update of the caret position.
+     *
+     * @param ev the event for the caret update
      */
     public void caretUpdate(CaretEvent ev)
     {
@@ -514,12 +530,13 @@
   }
 
   /**
-   * currentRun
+   * Stores the <code>Element</code> at the current caret position. This
+   * is updated by address@hidden CaretTracker}.
    */
   Element currentRun;
 
   /**
-   * inputAttributes
+   * The current input attributes. This is updated by address@hidden 
CaretTracker}.
    */
   MutableAttributeSet inputAttributes;
 
@@ -535,7 +552,7 @@
   StyledViewFactory viewFactory;
 
   /**
-   * Constructor StyledEditorKit
+   * Creates a new instance of <code>StyledEditorKit</code>.
    */
   public StyledEditorKit()
   {
@@ -543,8 +560,9 @@
   }
 
   /**
-   * clone
-   * @returns Object
+   * Creates an exact copy of this <code>StyledEditorKit</code>.
+   *
+   * @return an exact copy of this <code>StyledEditorKit</code>
    */
   public Object clone()
   {
@@ -554,8 +572,16 @@
   }
 
   /**
-   * getActions
-   * @returns Action[]
+   * Returns the <code>Action</code>s supported by this address@hidden 
EditorKit}.
+   * This includes the address@hidden BoldAction}, address@hidden 
ItalicAction} and
+   * address@hidden UnderlineAction} as well as the <code>Action</code>s 
supported
+   * by address@hidden DefaultEditorKit}.
+   *
+   * The other <code>Action</code>s of <code>StyledEditorKit</code> are not
+   * returned here, since they require a parameter and thus custom
+   * instantiation.
+   *
+   * @return the <code>Action</code>s supported by this address@hidden 
EditorKit}
    */
   public Action[] getActions()
   {
@@ -566,8 +592,10 @@
   }
 
   /**
-   * getInputAttributes
-   * @returns MutableAttributeSet
+   * Returns the current input attributes. These are automatically set on
+   * any newly inserted content, if not specified otherwise.
+   *
+   * @return the current input attributes
    */
   public MutableAttributeSet getInputAttributes()
   {
@@ -575,8 +603,11 @@
   }
 
   /**
-   * getCharacterAttributeRun
-   * @returns Element
+   * Returns the address@hidden Element} that represents the character run at 
the
+   * current caret position.
+   *
+   * @return the address@hidden Element} that represents the character run at 
the
+   *         current caret position
    */
   public Element getCharacterAttributeRun()
   {
@@ -584,8 +615,12 @@
   }
 
   /**
-   * createDefaultDocument
-   * @returns Document
+   * Creates the default address@hidden Document} supported by this
+   * <code>EditorKit</code>. This is an instance of
+   * address@hidden DefaultStyledDocument} in this case but may be overridden 
by
+   * subclasses.
+   *
+   * @return an instance of <code>DefaultStyledDocument</code>
    */
   public Document createDefaultDocument()
   {
@@ -593,8 +628,12 @@
   }
 
   /**
-   * install
-   * @param component TODO
+   * Installs this <code>EditorKit</code> on the specified address@hidden 
JEditorPane}.
+   * This basically involves setting up required listeners on the
+   * <code>JEditorPane</code>.
+   *
+   * @param component the <code>JEditorPane</code> to install this
+   *        <code>EditorKit</code> on
    */
   public void install(JEditorPane component)
   {
@@ -603,8 +642,13 @@
   }
 
   /**
-   * deinstall
-   * @param component TODO
+   * Deinstalls this <code>EditorKit</code> from the specified
+   * address@hidden JEditorPane}. This basically involves removing all 
listeners from
+   * <code>JEditorPane</code> that have been set up by this
+   * <code>EditorKit</code>.
+   *
+   * @param component the <code>JEditorPane</code> from which to deinstall this
+   *        <code>EditorKit</code>
    */
   public void deinstall(JEditorPane component)
   {
@@ -615,8 +659,20 @@
   }
 
   /**
-   * getViewFactory
-   * @returns ViewFactory
+   * Returns a address@hidden ViewFactory} that is able to create 
address@hidden View}s
+   * for address@hidden Element}s that are supported by this 
<code>EditorKit</code>,
+   * namely the following types of <code>Element</code>s:
+   *
+   * <ul>
+   * <li>address@hidden AbstractDocument.ContentElementName}</li>
+   * <li>address@hidden AbstractDocument.ParagraphElementName}</li>
+   * <li>address@hidden AbstractDocument.SectionElementName}</li>
+   * <li>address@hidden StyleContext.ComponentElementName}</li>
+   * <li>address@hidden StyleContext.IconElementName}</li>
+   * </ul>
+   *
+   * @return a address@hidden ViewFactory} that is able to create 
address@hidden View}s
+   *          for address@hidden Element}s that are supported by this 
<code>EditorKit</code>
    */
   public ViewFactory getViewFactory()
   {
@@ -626,9 +682,17 @@
   }
 
   /**
-   * createInputAttributes
-   * @param element TODO
-   * @param set TODO
+   * Copies the text attributes from <code>element</code> to <code>set</code>.
+   * This is called everytime when the caret position changes to keep
+   * track of the current input attributes. The attributes in <code>set</code>
+   * are cleaned before adding the attributes of <code>element</code>.
+   *
+   * This method filters out attributes for element names, <code>Icon</code>s
+   * and <code>Component</code>s.
+   *
+   * @param element the <code>Element</code> from which to copy the text
+   *         attributes
+   * @param set the inputAttributes to copy the attributes to
    */
   protected void createInputAttributes(Element element,
                                       MutableAttributeSet set)