Doc additions.

2008-12-29  Matthias Clasen  <mclasen@redhat.com>

        * gtk/gtkentry.c:
        * gtk/gtktextview.c:
        * gtk/gtkeditable.c:
        * gtk/gtktextbuffer.c: Doc additions.



svn path=/trunk/; revision=22000

5 files changed, 169 insertions, 5 deletions

diff --git a/ChangeLog b/ChangeLog
index c6a144fce9..d004d25305 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2008-12-29  Matthias Clasen  <mclasen@redhat.com>
+
+	* gtk/gtkentry.c:
+	* gtk/gtktextview.c:
+	* gtk/gtkeditable.c: 
+	* gtk/gtktextbuffer.c: Doc additions.
+
 2008-12-29  Tor Lillqvist  <tml@novell.com>
 
 	* gtk/gtk.symbols: Add missing symbols from gtkentry.c.
diff --git a/gtk/gtkeditable.c b/gtk/gtkeditable.c
index 37c29c1354..8887b8ef62 100644
--- a/gtk/gtkeditable.c
+++ b/gtk/gtkeditable.c
@@ -119,6 +119,19 @@ gtk_editable_base_init (gpointer g_class)
 		    G_TYPE_NONE, 2,
 		    G_TYPE_INT,
 		    G_TYPE_INT);
+      /**
+       * GtkEditable::changed:
+       * @editable: the object which received the signal
+       *
+       * The ::changed signal is emitted at the end of a single
+       * user-visible operation on the contents of the #GtkEditable.
+       *
+       * E.g., a paste operation that replaces the contents of the
+       * selection will cause only one signal emission (even though it
+       * is implemented by first deleting the selection, then inserting
+       * the new content, and may cause multiple ::notify::text signals
+       * to be emitted).
+       */ 
       g_signal_new (I_("changed"),
 		    GTK_TYPE_EDITABLE,
 		    G_SIGNAL_RUN_LAST,
diff --git a/gtk/gtkentry.c b/gtk/gtkentry.c
index cd39c967ca..bf96284369 100644
--- a/gtk/gtkentry.c
+++ b/gtk/gtkentry.c
@@ -1095,6 +1095,17 @@ gtk_entry_class_init (GtkEntryClass *class)
                                                                  TRUE,
                                                                  GTK_PARAM_READABLE));
   
+  /**
+   * GtkEntry::populate-popup:
+   * @entry: The entry on which the signal is emitted
+   * @menu: the menu that is being populated
+   *
+   * The ::populate-popup signal gets emitted before showing the 
+   * context menu of the entry. 
+   *
+   * If you need to add items to the context menu, connect
+   * to this signal and append your menuitems to the @menu.
+   */
   signals[POPULATE_POPUP] =
     g_signal_new (I_("populate-popup"),
 		  G_OBJECT_CLASS_TYPE (gobject_class),
@@ -1107,6 +1118,19 @@ gtk_entry_class_init (GtkEntryClass *class)
   
  /* Action signals */
   
+  /**
+   * GtkEntry::activate:
+   * @entry: The entry on which the signal is emitted
+   *
+   * A  <link linkend="keybinding-signals">keybinding signal</link>
+   * which gets emitted when the user activates the entry.
+   * 
+   * Applications should not connect to it, but may emit it with
+   * g_signal_emit_by_name() if they need to control scrolling
+   * programmatically.
+   *
+   * The default bindings for this signal are all forms of the Enter key.
+   */
   signals[ACTIVATE] =
     g_signal_new (I_("activate"),
 		  G_OBJECT_CLASS_TYPE (gobject_class),
@@ -1129,6 +1153,18 @@ gtk_entry_class_init (GtkEntryClass *class)
 		  G_TYPE_INT,
 		  G_TYPE_BOOLEAN);
 
+  /**
+   * GtkEntry::insert-at-cursor:
+   * @entry: the object which received the signal
+   * @string: the string to insert
+   *
+   * The ::insert-at-cursor signal is a
+   * <link linkend="keybinding-signals">keybinding signal</link>
+   * which gets emitted when the user initiates the insertion of a
+   * fixed string at the cursor.
+   *
+   * This signal has no default bindings.
+   */
   signals[INSERT_AT_CURSOR] = 
     g_signal_new (I_("insert-at-cursor"),
 		  G_OBJECT_CLASS_TYPE (gobject_class),
@@ -1139,6 +1175,24 @@ gtk_entry_class_init (GtkEntryClass *class)
 		  G_TYPE_NONE, 1,
 		  G_TYPE_STRING);
 
+  /**
+   * GtkEntry::delete-from-cursor:
+   * @entry: the object which received the signal
+   * @type: the granularity of the deletion, as a #GtkDeleteType
+   * @count: the number of @type units to delete
+   *
+   * The ::delete-from-cursor signal is a
+   * <link linkend="keybinding-signals">keybinding signal</link>
+   * which gets emitted when the user initiates a text deletion.
+   *
+   * If the @type is %GTK_DELETE_CHARS, GTK+ deletes the selection
+   * if there is one, otherwise it deletes the requested number
+   * of characters.
+   *
+   * The default bindings for this signal are
+   * Delete for deleting a character and Ctrl-Delete for
+   * deleting a word.
+   */
   signals[DELETE_FROM_CURSOR] = 
     g_signal_new (I_("delete-from-cursor"),
 		  G_OBJECT_CLASS_TYPE (gobject_class),
@@ -1150,6 +1204,17 @@ gtk_entry_class_init (GtkEntryClass *class)
 		  GTK_TYPE_DELETE_TYPE,
 		  G_TYPE_INT);
 
+  /**
+   * GtkEntry::backspace:
+   * @entry: the object which received the signal
+   *
+   * The ::backspace signal is a
+   * <link linkend="keybinding-signals">keybinding signal</link>
+   * which gets emitted when the user asks for it.
+   *
+   * The default bindings for this signal are
+   * Backspace and Shift-Backspace.
+   */
   signals[BACKSPACE] =
     g_signal_new (I_("backspace"),
 		  G_OBJECT_CLASS_TYPE (gobject_class),
@@ -1159,6 +1224,17 @@ gtk_entry_class_init (GtkEntryClass *class)
 		  _gtk_marshal_VOID__VOID,
 		  G_TYPE_NONE, 0);
 
+  /**
+   * GtkEntry::cut-clipboard:
+   * @entry: the object which received the signal
+   *
+   * The ::cut-clipboard signal is a
+   * <link linkend="keybinding-signals">keybinding signal</link>
+   * which gets emitted to cut the selection to the clipboard.
+   *
+   * The default bindings for this signal are
+   * Ctrl-x and Shift-Delete.
+   */
   signals[CUT_CLIPBOARD] =
     g_signal_new (I_("cut-clipboard"),
 		  G_OBJECT_CLASS_TYPE (gobject_class),
@@ -1168,6 +1244,17 @@ gtk_entry_class_init (GtkEntryClass *class)
 		  _gtk_marshal_VOID__VOID,
 		  G_TYPE_NONE, 0);
 
+  /**
+   * GtkEntry::copy-clipboard:
+   * @entry: the object which received the signal
+   *
+   * The ::copy-clipboard signal is a
+   * <link linkend="keybinding-signals">keybinding signal</link>
+   * which gets emitted to copy the selection to the clipboard.
+   *
+   * The default bindings for this signal are
+   * Ctrl-c and Ctrl-Insert.
+   */
   signals[COPY_CLIPBOARD] =
     g_signal_new (I_("copy-clipboard"),
 		  G_OBJECT_CLASS_TYPE (gobject_class),
@@ -1177,6 +1264,18 @@ gtk_entry_class_init (GtkEntryClass *class)
 		  _gtk_marshal_VOID__VOID,
 		  G_TYPE_NONE, 0);
 
+  /**
+   * GtkEntry::paste-clipboard:
+   * @entry: the object which received the signal
+   *
+   * The ::paste-clipboard signal is a
+   * <link linkend="keybinding-signals">keybinding signal</link>
+   * which gets emitted to paste the contents of the clipboard
+   * into the text view.
+   *
+   * The default bindings for this signal are
+   * Ctrl-v and Shift-Insert.
+   */
   signals[PASTE_CLIPBOARD] =
     g_signal_new (I_("paste-clipboard"),
 		  G_OBJECT_CLASS_TYPE (gobject_class),
@@ -1186,6 +1285,16 @@ gtk_entry_class_init (GtkEntryClass *class)
 		  _gtk_marshal_VOID__VOID,
 		  G_TYPE_NONE, 0);
 
+  /**
+   * GtkEntry::toggle-overwrite:
+   * @entry: the object which received the signal
+   *
+   * The ::toggle-overwrite signal is a
+   * <link linkend="keybinding-signals">keybinding signal</link>
+   * which gets emitted to toggle the overwrite mode of the entry.
+   *
+   * The default bindings for this signal is Insert.
+   */
   signals[TOGGLE_OVERWRITE] =
     g_signal_new (I_("toggle-overwrite"),
 		  G_OBJECT_CLASS_TYPE (gobject_class),
diff --git a/gtk/gtktextbuffer.c b/gtk/gtktextbuffer.c
index 080e5e0e14..69a30aece3 100644
--- a/gtk/gtktextbuffer.c
+++ b/gtk/gtktextbuffer.c
@@ -560,7 +560,7 @@ gtk_text_buffer_class_init (GtkTextBufferClass *klass)
    * @textbuffer: the object which received the signal
    * 
    * The ::end-user-action signal is emitted at the end of a single
-   * user-visible operation #GtkTextBuffer.
+   * user-visible operation on the #GtkTextBuffer.
    * 
    * See also: 
    * gtk_text_buffer_end_user_action(),
diff --git a/gtk/gtktextview.c b/gtk/gtktextview.c
index a45b390f5a..0c10a4d260 100644
--- a/gtk/gtktextview.c
+++ b/gtk/gtktextview.c
@@ -764,6 +764,18 @@ gtk_text_view_class_init (GtkTextViewClass *klass)
                                 GTK_TYPE_SCROLL_STEP,
                                 G_TYPE_INT);
 
+  /**
+   * GtkTextView::set-anchor:
+   * @text_view: the object which received the signal
+   *
+   * The ::set-anchor signal is a
+   * <link linkend="keybinding-signals">keybinding signal</link>
+   * which gets emitted when the user initiates setting the "anchor" 
+   * mark. The "anchor" mark gets placed at the same position as the
+   * "insert" mark.
+   *
+   * This signal has no default bindings.
+   */   
   signals[SET_ANCHOR] =
     g_signal_new (I_("set-anchor"),
 		  G_OBJECT_CLASS_TYPE (gobject_class),
@@ -773,6 +785,18 @@ gtk_text_view_class_init (GtkTextViewClass *klass)
 		  _gtk_marshal_VOID__VOID,
 		  G_TYPE_NONE, 0);
 
+  /**
+   * GtkTextView::insert-at-cursor:
+   * @text_view: the object which received the signal
+   * @string: the string to insert
+   *
+   * The ::insert-at-cursor signal is a
+   * <link linkend="keybinding-signals">keybinding signal</link>
+   * which gets emitted when the user initiates the insertion of a 
+   * fixed string at the cursor.
+   *
+   * This signal has no default bindings.
+   */
   signals[INSERT_AT_CURSOR] =
     g_signal_new (I_("insert-at-cursor"),
 		  G_OBJECT_CLASS_TYPE (gobject_class),
@@ -900,7 +924,7 @@ gtk_text_view_class_init (GtkTextViewClass *klass)
    *
    * The ::toggle-overwrite signal is a 
    * <link linkend="keybinding-signals">keybinding signal</link> 
-   * which gets emitted to change the editability of the text view.
+   * which gets emitted to toggle the overwrite mode of the text view.
    * 
    * The default bindings for this signal is Insert.
    */ 
@@ -934,6 +958,17 @@ gtk_text_view_class_init (GtkTextViewClass *klass)
 		  GTK_TYPE_ADJUSTMENT);
   widget_class->set_scroll_adjustments_signal = signals[SET_SCROLL_ADJUSTMENTS];
 
+  /**
+   * GtkTextView::populate-popup:
+   * @entry: The text view on which the signal is emitted
+   * @menu: the menu that is being populated
+   *
+   * The ::populate-popup signal gets emitted before showing the 
+   * context menu of the text view.
+   *
+   * If you need to add items to the context menu, connect
+   * to this signal and append your menuitems to the @menu.
+   */
   signals[POPULATE_POPUP] =
     g_signal_new (I_("populate-popup"),
 		  G_OBJECT_CLASS_TYPE (gobject_class),
@@ -1140,17 +1175,17 @@ gtk_text_view_class_init (GtkTextViewClass *klass)
 				G_TYPE_INT, -1);
 
   gtk_binding_entry_add_signal (binding_set, GDK_Delete, GDK_SHIFT_MASK | GDK_CONTROL_MASK,
-				"delete_from_cursor", 2,
+				"delete-from-cursor", 2,
 				G_TYPE_ENUM, GTK_DELETE_PARAGRAPH_ENDS,
 				G_TYPE_INT, 1);
 
   gtk_binding_entry_add_signal (binding_set, GDK_KP_Delete, GDK_SHIFT_MASK | GDK_CONTROL_MASK,
-				"delete_from_cursor", 2,
+				"delete-from-cursor", 2,
 				G_TYPE_ENUM, GTK_DELETE_PARAGRAPH_ENDS,
 				G_TYPE_INT, 1);
 
   gtk_binding_entry_add_signal (binding_set, GDK_BackSpace, GDK_SHIFT_MASK | GDK_CONTROL_MASK,
-				"delete_from_cursor", 2,
+				"delete-from-cursor", 2,
 				G_TYPE_ENUM, GTK_DELETE_PARAGRAPH_ENDS,
 				G_TYPE_INT, -1);