API documentation, GtkTextBuffer signals

[Søren Wedel Nielsen <soren wedel nielsen gmail com>]

Hi, 

I have written some documentation of the GtkTextBuffer signals. 

If this is useful I will try to find time to continue with more signals
- they seems to be neglected in most of the documentation.

I include a patch against 2.6.7 and would like to hear your
comments/criticism.

Is this useful? How do I submit it for inclusion? 

S�

--- orig/gtk+-2.6.7/gtk/gtktextbuffer.c	2005-03-20 07:25:29.000000000 +0100
+++ gtk+-2.6.7/gtk/gtktextbuffer.c	2005-09-19 21:28:12.844393536 +0200
@@ -186,6 +186,23 @@
                                                         GTK_TYPE_TEXT_TAG_TABLE,
                                                         G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
 
+  /**
+   * GtkTextBuffer::insert-text:
+   * @textbuffer: the object which received the signal.
+   * @location: position to insert @text in @textbuffer.
+   * @text: the UTF-8 text to be inserted.
+   * @len: length of the inserted text in bytes.
+   *
+   * The insert_text signal is emitted to insert text in a #GtkTextBuffer 
+   * (see gtk_text_buffer_insert() ).
+   * Insertion actually occurs in the default handler.  
+   * Note that if your handler runs before the default handler it must not 
+   * invalidate the @location iter (or has to revalidate it). 
+   * There is no need to keep the iter valid in handlers
+   * which run after the default handler (see g_signal_connect_after() ).
+   * The default signal handler revalidates it to point to the end of the 
+   * inserted text.
+   */
   signals[INSERT_TEXT] =
     g_signal_new ("insert_text",
                   G_OBJECT_CLASS_TYPE (object_class),
@@ -199,6 +216,22 @@
                   G_TYPE_STRING | G_SIGNAL_TYPE_STATIC_SCOPE,
                   G_TYPE_INT);
 
+  /**
+   * GtkTextBuffer::insert-pixbuf:
+   * @textbuffer: the object which received the signal.
+   * @location: position to insert @pixbuf in @textbuffer.
+   * @pixbuf: the #GdkPixbuf to be inserted.
+   *
+   * The insert_pixbuf signal is emitted to insert a
+   * #GdkPixbuf in a #GtkTextBuffer.
+   * Insertion actually occurs in the default handler.
+   * Note that if your handler runs before the default handler it must not 
+   * invalidate the @location iter (or has to revalidate it). 
+   * There is no need to keep the iter valid in handlers
+   * which run after the default handler (see g_signal_connect_after() ).
+   * The default signal handler revalidates it to be placed after the 
+   * inserted @pixbuf.
+   */
   signals[INSERT_PIXBUF] =
     g_signal_new ("insert_pixbuf",
                   G_OBJECT_CLASS_TYPE (object_class),
@@ -211,6 +244,23 @@
                   GTK_TYPE_TEXT_ITER | G_SIGNAL_TYPE_STATIC_SCOPE,
                   GDK_TYPE_PIXBUF);
 
+
+  /**
+   * GtkTextBuffer::insert-child-anchor:
+   * @textbuffer: the object which received the signal.
+   * @location: position to insert @anchor in @textbuffer.
+   * @anchor: the #GtkTextChildAnchor to be inserted.
+   *
+   * The insert_child_anchor signal is emitted to insert a
+   * #GtkTextChildAnchor in a #GtkTextBuffer.
+   * Insertion actually occurs in the default handler.
+   * Note that if your handler runs before the default handler it must not 
+   * invalidate the @location iter (or has to revalidate it). 
+   * There is no need to keep the iter valid in handlers
+   * which run after the default handler (see g_signal_connect_after() ).
+   * The default signal handler revalidates it to be placed after the 
+   * inserted @anchor.
+   */
   signals[INSERT_CHILD_ANCHOR] =
     g_signal_new ("insert_child_anchor",
                   G_OBJECT_CLASS_TYPE (object_class),
@@ -224,17 +274,20 @@
                   GTK_TYPE_TEXT_CHILD_ANCHOR);
   
   /**
-   * GtkTextBuffer::delete_range:
-   * @buffer: the object which received the signal.
-   * @start: the start of the range to be deleted
-   * @end: the end of the range to be deleted
+   * GtkTextBuffer::delete-range:
+   * @textbuffer: the object which received the signal.
+   * @start: the start of the range to be deleted.
+   * @end: the end of the range to be deleted.
    *
-   * The ::delete_range signal is emitted to delete a range from 
-   * a #GtkTextBuffer. Note that your handler must not invalidate the
-   * @start and @end iters (or has to revalidate them), if it runs before the 
-   * default handler. There is no need to keep the iters valid in handlers
+   * The delete_range signal is emitted to delete a range 
+   * from a #GtkTextBuffer. 
+   * Note that if your handler runs before the default handler it must not 
+   * invalidate the @start and @end iters (or has to revalidate them). 
+   * There is no need to keep the iters valid in handlers
    * which run after the default handler (see g_signal_connect_after()), but
-   * those don't have access to the deleted text.
+   * those do not have access to the deleted text.
+   * The default signal handler revalidates the @start and @end iters to 
+   * both point to the place where the text was deleted.
    */
   signals[DELETE_RANGE] =
     g_signal_new ("delete_range",
@@ -248,6 +301,13 @@
                   GTK_TYPE_TEXT_ITER | G_SIGNAL_TYPE_STATIC_SCOPE,
                   GTK_TYPE_TEXT_ITER | G_SIGNAL_TYPE_STATIC_SCOPE);
 
+  /**
+   * GtkTextBuffer::changed:
+   * @textbuffer: the object which received the signal.
+   *
+   * The changed signal is emitted when the content of a #GtkTextBuffer 
+   * has changed.
+   */
   signals[CHANGED] =
     g_signal_new ("changed",
                   G_OBJECT_CLASS_TYPE (object_class),
@@ -258,6 +318,13 @@
                   G_TYPE_NONE,
                   0);
 
+  /**
+   * GtkTextBuffer::modified-changed:
+   * @textbuffer: the object which received the signal.
+   *
+   * The modified_changed signal is emitted when the modified bit of a 
+   * #GtkTextBuffer flips (see gtk_text_buffer_set_modified() ).
+   */
   signals[MODIFIED_CHANGED] =
     g_signal_new ("modified_changed",
                   G_OBJECT_CLASS_TYPE (object_class),
@@ -268,6 +335,16 @@
                   G_TYPE_NONE,
                   0);
 
+  /**
+   * GtkTextBuffer::mark-set:
+   * @textbuffer: the object which received the signal.
+   * @location: The location of @mark in @textbuffer.
+   * @mark: The mark that is set.
+   * 
+   * The mark_set signal is emitted as notification
+   * after a #GtkTextMark is set (e.g. by gtk_text_buffer_create_mark() or
+   * gtk_text_buffer_move_mark() ).
+   */
   signals[MARK_SET] =
     g_signal_new ("mark_set",
                   G_OBJECT_CLASS_TYPE (object_class),
@@ -280,6 +357,14 @@
                   GTK_TYPE_TEXT_ITER,
                   GTK_TYPE_TEXT_MARK);
 
+  /**
+   * GtkTextBuffer::mark-deleted:
+   * @textbuffer: the object which received the signal.
+   * @mark: The mark that was deleted.
+   * 
+   * The mark_deleted signal is emitted as notification
+   * after a #GtkTextMark is deleted. 
+   */
   signals[MARK_DELETED] =
     g_signal_new ("mark_deleted",
                   G_OBJECT_CLASS_TYPE (object_class),
@@ -290,7 +375,23 @@
                   G_TYPE_NONE,
                   1,
                   GTK_TYPE_TEXT_MARK);
-  
+
+   /**
+   * GtkTextBuffer::apply-tag:
+   * @textbuffer: the object which received the signal.
+   * @tag: the applied tag.
+   * @start: the start of the range the tag is applied to.
+   * @end: the end of the range the tag is applied to.
+   *
+   * The apply_tag signal is emitted to apply a tag to a
+   * range of text in a #GtkTextBuffer 
+   * (see gtk_text_buffer_apply_tag() ). 
+   * Applying actually occurs in the default handler.
+   * Note that if your handler runs before the default handler it must not 
+   * invalidate the @start and @end iters (or has to revalidate them). 
+   * There is no need to keep the iters valid in handlers
+   * which run after the default handler (see g_signal_connect_after() ).
+   */ 
   signals[APPLY_TAG] =
     g_signal_new ("apply_tag",
                   G_OBJECT_CLASS_TYPE (object_class),
@@ -304,6 +405,23 @@
                   GTK_TYPE_TEXT_ITER,
                   GTK_TYPE_TEXT_ITER);
 
+
+   /**
+   * GtkTextBuffer::remove-tag:
+   * @textbuffer: the object which received the signal.
+   * @tag: the tag to be removed.
+   * @start: the start of the range the tag is removed from.
+   * @end: the end of the range the tag is removed from.
+   *
+   * The remove_tag signal is emitted to remove all occurrences of @tag from a
+   * range of text in a #GtkTextBuffer 
+   * (see gtk_text_buffer_remove_tag() ). 
+   * Removal actually occurs in the default handler.
+   * Note that if your handler runs before the default handler it must not 
+   * invalidate the @start and @end iters (or has to revalidate them). 
+   * There is no need to keep the iters valid in handlers
+   * which run after the default handler (see g_signal_connect_after() ).
+   */ 
   signals[REMOVE_TAG] =
     g_signal_new ("remove_tag",
                   G_OBJECT_CLASS_TYPE (object_class),
@@ -317,6 +435,14 @@
                   GTK_TYPE_TEXT_ITER,
                   GTK_TYPE_TEXT_ITER);
 
+   /**
+   * GtkTextBuffer::begin-user-action:
+   * @textbuffer: the object which received the signal.
+   *
+   * The begin_user_action signal is emitted at the beginning of a single
+   * user-visible operation on a #GtkTextBuffer
+   * (see gtk_text_buffer_begin_user_action() ).
+   */ 
   signals[BEGIN_USER_ACTION] =
     g_signal_new ("begin_user_action",
                   G_OBJECT_CLASS_TYPE (object_class),
@@ -327,6 +453,14 @@
                   G_TYPE_NONE,
                   0);
 
+   /**
+   * GtkTextBuffer::end-user-action:
+   * @textbuffer: the object which received the signal.
+   *
+   * The end_user_action signal is emitted at the end of a single
+   * user-visible operation #GtkTextBuffer 
+   * (see gtk_text_buffer_end_user_action() ).
+   */ 
   signals[END_USER_ACTION] =
     g_signal_new ("end_user_action",
                   G_OBJECT_CLASS_TYPE (object_class),