[kaffe] CVS kaffe (robilad): Resynced with GNU Classpath: better swing text api docs

[Kaffe CVS]

PatchSet 6414 
Date: 2005/04/23 20:56:01
Author: robilad
Branch: HEAD
Tag: (none) 
Log:
Resynced with GNU Classpath: better swing text api docs

2005-04-23  Dalibor Topic  <robilad at kaffe.org>

        Resynced with GNU Classpath:

        2005-04-23  Roman Kennke  <roman at kennke.org>

        * javax/swing/text/Document.java:
        Added API documentation comments.

Members: 
	ChangeLog:1.3937->1.3938 
	libraries/javalib/javax/swing/text/Document.java:1.3->1.4 

Index: kaffe/ChangeLog
diff -u kaffe/ChangeLog:1.3937 kaffe/ChangeLog:1.3938
--- kaffe/ChangeLog:1.3937	Sat Apr 23 12:53:58 2005
+++ kaffe/ChangeLog	Sat Apr 23 12:56:01 2005
@@ -4,6 +4,15 @@
 
 	2005-04-23  Roman Kennke  <roman at kennke.org>
 
+        * javax/swing/text/Document.java:
+        Added API documentation comments.
+
+2005-04-23  Dalibor Topic  <robilad at kaffe.org>
+
+	Resynced with GNU Classpath:
+
+	2005-04-23  Roman Kennke  <roman at kennke.org>
+
         * javax/swing/text/AbstractDocument.java
         (getDocumentProperties): Implemented.
         (setDocumentProperties): Implemented.
Index: kaffe/libraries/javalib/javax/swing/text/Document.java
diff -u kaffe/libraries/javalib/javax/swing/text/Document.java:1.3 kaffe/libraries/javalib/javax/swing/text/Document.java:1.4
--- kaffe/libraries/javalib/javax/swing/text/Document.java:1.3	Sun Oct 24 13:39:22 2004
+++ kaffe/libraries/javalib/javax/swing/text/Document.java	Sat Apr 23 12:56:02 2005
@@ -40,48 +40,182 @@
 import javax.swing.event.DocumentListener;
 import javax.swing.event.UndoableEditListener;
 
-
+/**
+ * A Document is the model that backs up all text components in Swing.
+ * This interface supports different kinds of implementations, from
+ * simple plain text model up to complex styled HTML or RTF models.
+ */
 public interface Document
 {
+  /**
+   * The key for the property that describes the source of a document.
+   */
   String StreamDescriptionProperty = "stream";
+
+  /**
+   * The key for the property that is the title of a document.
+   */
   String TitleProperty = "title";
 
+  /**
+   * Adds a {@link DocumentListener} to this document.
+   *
+   * @param listener the DocumentListener to add
+   */
   void addDocumentListener(DocumentListener listener);
 
+  /**
+   * Adds an {@link UndoableEditListener} to this document.
+   *
+   * @param listener the UndoableEditListener to add
+   */
   void addUndoableEditListener(UndoableEditListener listener);
 
+  /**
+   * Creates a mark in the character content at the specified offset.
+   *
+   * @param offs the offset where to place the mark
+   *
+   * @return the created Position object
+   *
+   * @throws BadLocationException of the specified offset is not a valid
+   *         position in the documents content
+   */
   Position createPosition(int offs)
     throws BadLocationException;
 
+  /**
+   * Returns the default root element. Views should be using this element
+   * unless other mechanisms for assigning views to element structure is
+   * provided.
+   *
+   * @return the default root element
+   */
   Element getDefaultRootElement();
 
+  /**
+   * Returns the position that marks the end of the document.
+   *
+   * @return the position that marks the end of the document
+   */
   Position getEndPosition();
 
+  /**
+   * Returns the length of the document content.
+   *
+   * @return the length of the document content
+   */
   int getLength();
 
+  /**
+   * Returns a document property with the specified key.
+   *
+   * @param key the (non-null) key for the property to fetch
+   *
+   * @return the property for <code>key</code> or null if no such property
+   *         is stored
+   */
   Object getProperty(Object key);
 
+  /**
+   * Returns the root elements of the document content.
+   *
+   * @return the root elements of the document content
+   */
   Element[] getRootElements();
 
+  /**
+   * Returns the position that marks the beginning of the document
+   * content.
+   *
+   * @return the start position
+   */
   Position getStartPosition();
 
+  /**
+   * Returns the textual content starting at <code>offset</code> with
+   * a length of <code>length</code>.
+   *
+   * @param offset the beginning of the text fragment to fetch
+   * @param length the length of the text fragment to fetch
+   *
+   * @return the text fragment starting at <code>offset</code> with
+   *         a length of <code>length</code>
+   *
+   * @throws BadLocationException if <code>offset</code> or <code>length</code>
+   *         are no valid locations in the document content
+   */
   String getText(int offset, int length)
     throws BadLocationException;
 
+  /**
+   * Fetch the textual content starting at <code>offset</code> with
+   * a length of <code>length</code> and store it in <code>txt</code>.
+   *
+   * @param offset the beginning of the text fragment to fetch
+   * @param length the length of the text fragment to fetch
+   * @param txt the Segment where to store the text fragment
+   *
+   * @throws BadLocationException if <code>offset</code> or <code>length</code>
+   *         are no valid locations in the document content
+   */
   void getText(int offset, int length, Segment txt)
     throws BadLocationException;
 
+  /**
+   * Inserts a piece of text with an AttributeSet at the specified
+   * <code>offset</code>.
+   *
+   * @param offset the location where to insert the content
+   * @param str the textual content to insert
+   * @param a the Attributes associated with the piece of text
+   *
+   * @throws BadLocationException if <code>offset</code>
+   *         is not a valid location in the document content
+   */
   void insertString(int offset, String str, AttributeSet a)
     throws BadLocationException;
 
+  /**
+   * Sets a document property.
+   *
+   * @param key the key of the property
+   * @param value the value of the property
+   */
   void putProperty(Object key, Object value);
 
+  /**
+   * Removes a piece of content.
+   *
+   * @param offs the location of the fragment to remove
+   * @param len the length of the fragment to remove
+   *
+   * @throws BadLocationException if <code>offs</code> or <code>len</code>
+   *         are no valid locations in the document content
+   */
   void remove(int offs, int len)
     throws BadLocationException;
 
+  /**
+   * Removes a DocumentListener from this Document.
+   *
+   * @param listener the DocumentListener to remove
+   */
   void removeDocumentListener(DocumentListener listener);
 
+  /**
+   * Removes an UndoableEditListener from this Document.
+   *
+   * @param listener the UndoableEditListener to remove
+   */
   void removeUndoableEditListener(UndoableEditListener listener);
 
+  /**
+   * This allows the Document to be rendered safely. It is made sure that
+   * the Runnable can read the document without any changes while reading.
+   * The Runnable is not allowed to change the Document itself.
+   *
+   * @param r the Runnable that renders the Document
+   */
   void render(Runnable r);
 }