Add more documentation.

svn path=/trunk/; revision=18453

4 files changed, 84 insertions, 42 deletions

diff --git a/gtk/gtkcelleditable.c b/gtk/gtkcelleditable.c
index 0223022424..d50aac5e14 100644
--- a/gtk/gtkcelleditable.c
+++ b/gtk/gtkcelleditable.c
@@ -63,6 +63,20 @@ gtk_cell_editable_base_init (gpointer g_class)
 
   if (! initialized)
     {
+      /**
+       * GtkCellEditable::editing-done:
+       * @cell_editable: the object on which the signal was emitted
+       *
+       * This signal is a sign for the cell renderer to update its 
+       * value from the @cell_editable. 
+       *
+       * Implementations of #GtkCellEditable are responsible for 
+       * emitting this signal when they are done editing, e.g. 
+       * #GtkEntry is emitting it when the user presses Enter.
+       *
+       * gtk_cell_editable_editing_done() is a convenience method
+       * for emitting ::editing-done. 
+       */
       g_signal_new (I_("editing_done"),
                     GTK_TYPE_CELL_EDITABLE,
                     G_SIGNAL_RUN_LAST,
@@ -70,6 +84,23 @@ gtk_cell_editable_base_init (gpointer g_class)
                     NULL, NULL,
                     _gtk_marshal_VOID__VOID,
                     G_TYPE_NONE, 0);
+
+      /**
+       * GtkCellEditable::remove-widget:
+       * @cell_editable: the object on which the signal was emitted
+       *
+       * This signal is meant to indicate that the cell is finished 
+       * editing, and the widget may now be destroyed. 
+       *
+       * Implementations of #GtkCellEditable are responsible for 
+       * emitting this signal when they are done editing. It must
+       * be emitted after the #GtkCellEditable::editing-done signal, 
+       * to give the cell renderer a chance to update the cell's value 
+       * before the widget is removed. 
+       *
+       * gtk_cell_editable_remove_widget() is a convenience method
+       * for emitting ::remove-widget. 
+       */
       g_signal_new (I_("remove_widget"),
                     GTK_TYPE_CELL_EDITABLE,
                     G_SIGNAL_RUN_LAST,
@@ -86,9 +117,9 @@ gtk_cell_editable_base_init (gpointer g_class)
  * @cell_editable: A #GtkCellEditable
  * @event: A #GdkEvent, or %NULL
  * 
- * Begins editing on a @cell_editable.  @event is the #GdkEvent that began the
- * editing process.  It may be %NULL, in the instance that editing was initiated
- * through programatic means.
+ * Begins editing on a @cell_editable. @event is the #GdkEvent that began 
+ * the editing process. It may be %NULL, in the instance that editing was 
+ * initiated through programatic means.
  **/
 void
 gtk_cell_editable_start_editing (GtkCellEditable *cell_editable,
@@ -103,8 +134,7 @@ gtk_cell_editable_start_editing (GtkCellEditable *cell_editable,
  * gtk_cell_editable_editing_done:
  * @cell_editable: A #GtkTreeEditable
  * 
- * Emits the "editing_done" signal.  This signal is a sign for the cell renderer
- * to update its value from the cell.
+ * Emits the #GtkCellEditable::editing-done signal. 
  **/
 void
 gtk_cell_editable_editing_done (GtkCellEditable *cell_editable)
@@ -118,8 +148,7 @@ gtk_cell_editable_editing_done (GtkCellEditable *cell_editable)
  * gtk_cell_editable_remove_widget:
  * @cell_editable: A #GtkTreeEditable
  * 
- * Emits the "remove_widget" signal.  This signal is meant to indicate that the
- * cell is finished editing, and the widget may now be destroyed.
+ * Emits the #GtkCellEditable::remove-widget signal.  
  **/
 void
 gtk_cell_editable_remove_widget (GtkCellEditable *cell_editable)
diff --git a/gtk/gtkcellrenderer.c b/gtk/gtkcellrenderer.c
index f22830de65..28d200fd8e 100644
--- a/gtk/gtkcellrenderer.c
+++ b/gtk/gtkcellrenderer.c
@@ -111,7 +111,7 @@ gtk_cell_renderer_class_init (GtkCellRendererClass *class)
    * cell.  For example, an editable cell renderer could be written to cancel
    * editing when the user presses Escape. 
    *
-   * See also: gtk_cell_renderer_editing_canceled()
+   * See also: gtk_cell_renderer_stop_editing().
    *
    * Since: 2.4
    */
@@ -471,12 +471,13 @@ set_cell_bg_color (GtkCellRenderer *cell,
  * @width: location to return width needed to render a cell, or %NULL
  * @height: location to return height needed to render a cell, or %NULL
  *
- * Obtains the width and height needed to render the cell. Used by view widgets
- * to determine the appropriate size for the cell_area passed to
- * gtk_cell_renderer_render().  If @cell_area is not %NULL, fills in the x and y
- * offsets (if set) of the cell relative to this location.  Please note that the
- * values set in @width and @height, as well as those in @x_offset and @y_offset
- * are inclusive of the xpad and ypad properties.
+ * Obtains the width and height needed to render the cell. Used by view 
+ * widgets to determine the appropriate size for the cell_area passed to
+ * gtk_cell_renderer_render().  If @cell_area is not %NULL, fills in the
+ * x and y offsets (if set) of the cell relative to this location. 
+ *
+ * Please note that the values set in @width and @height, as well as those 
+ * in @x_offset and @y_offset are inclusive of the xpad and ypad properties.
  **/
 void
 gtk_cell_renderer_get_size (GtkCellRenderer *cell,
@@ -518,7 +519,8 @@ gtk_cell_renderer_get_size (GtkCellRenderer *cell,
  * @cell: a #GtkCellRenderer
  * @window: a #GdkDrawable to draw to
  * @widget: the widget owning @window
- * @background_area: entire cell area (including tree expanders and maybe padding on the sides)
+ * @background_area: entire cell area (including tree expanders and maybe 
+ *    padding on the sides)
  * @cell_area: area normally rendered by a cell renderer
  * @expose_area: area that actually needs updating
  * @flags: flags that affect rendering
@@ -530,7 +532,6 @@ gtk_cell_renderer_get_size (GtkCellRenderer *cell,
  * blank space around the cell, and also the area containing the tree expander;
  * so the @background_area rectangles for all cells tile to cover the entire
  * @window.  @expose_area is a clip rectangle.
- *
  **/
 void
 gtk_cell_renderer_render (GtkCellRenderer     *cell,
@@ -574,14 +575,15 @@ gtk_cell_renderer_render (GtkCellRenderer     *cell,
  * @cell: a #GtkCellRenderer
  * @event: a #GdkEvent
  * @widget: widget that received the event
- * @path: widget-dependent string representation of the event location; e.g. for #GtkTreeView, a string representation of #GtkTreePath
- * @background_area: background area as passed to @gtk_cell_renderer_render
- * @cell_area: cell area as passed to @gtk_cell_renderer_render
+ * @path: widget-dependent string representation of the event location; 
+ *    e.g. for #GtkTreeView, a string representation of #GtkTreePath
+ * @background_area: background area as passed to gtk_cell_renderer_render()
+ * @cell_area: cell area as passed to gtk_cell_renderer_render()
  * @flags: render flags
  *
- * Passes an activate event to the cell renderer for possible processing.  Some
- * cell renderers may use events; for example, #GtkCellRendererToggle toggles
- * when it gets a mouse click.
+ * Passes an activate event to the cell renderer for possible processing.  
+ * Some cell renderers may use events; for example, #GtkCellRendererToggle 
+ * toggles when it gets a mouse click.
  *
  * Return value: %TRUE if the event was consumed/handled
  **/
@@ -616,9 +618,10 @@ gtk_cell_renderer_activate (GtkCellRenderer      *cell,
  * @cell: a #GtkCellRenderer
  * @event: a #GdkEvent
  * @widget: widget that received the event
- * @path: widget-dependent string representation of the event location; e.g. for #GtkTreeView, a string representation of #GtkTreePath
- * @background_area: background area as passed to @gtk_cell_renderer_render
- * @cell_area: cell area as passed to @gtk_cell_renderer_render
+ * @path: widget-dependent string representation of the event location; 
+ *    e.g. for #GtkTreeView, a string representation of #GtkTreePath
+ * @background_area: background area as passed to gtk_cell_renderer_render()
+ * @cell_area: cell area as passed to gtk_cell_renderer_render()
  * @flags: render flags
  * 
  * Passes an activate event to the cell renderer for possible processing.
@@ -723,10 +726,12 @@ gtk_cell_renderer_get_fixed_size (GtkCellRenderer *cell,
  * gtk_cell_renderer_editing_canceled:
  * @cell: A #GtkCellRenderer
  * 
- * Causes the cell renderer to emit the "editing-canceled" signal.  This
- * function is for use only by implementations of cell renderers that need to
- * notify the client program that an editing process was canceled and the
- * changes were not committed.
+ * Causes the cell renderer to emit the #GtkCellRenderer::editing-canceled 
+ * signal.  
+ *
+ * This function is for use only by implementations of cell renderers that 
+ * need to notify the client program that an editing process was canceled 
+ * and the changes were not committed.
  *
  * Since: 2.4
  * Deprecated: 2.6: Use gtk_cell_renderer_stop_editing() instead
@@ -745,9 +750,12 @@ gtk_cell_renderer_editing_canceled (GtkCellRenderer *cell)
  * @canceled: %TRUE if the editing has been canceled
  * 
  * Informs the cell renderer that the editing is stopped.
- * If @canceled is %TRUE, the cell renderer will emit the "editing-canceled" 
- * signal. This function should be called by cell renderer implementations 
- * in response to the "editing-done" signal of #GtkCellEditable.
+ * If @canceled is %TRUE, the cell renderer will emit the 
+ * #GtkCellRenderer::editing-canceled signal. 
+ *
+ * This function should be called by cell renderer implementations 
+ * in response to the #GtkCellEditable::editing-done signal of 
+ * #GtkCellEditable.
  *
  * Since: 2.6
  **/
diff --git a/gtk/gtkcellrenderercombo.c b/gtk/gtkcellrenderercombo.c
index a1ed5f66b9..4f84d2905b 100644
--- a/gtk/gtkcellrenderercombo.c
+++ b/gtk/gtkcellrenderercombo.c
@@ -94,13 +94,15 @@ gtk_cell_renderer_combo_class_init (GtkCellRendererComboClass *klass)
   /**
    * GtkCellRendererCombo:text-column:
    *
-   * Specifies the model column which holds the possible values for the combo box. 
+   * Specifies the model column which holds the possible values for the 
+   * combo box. 
+   *
    * Note that this refers to the model specified in the model property, 
-   * <emphasis>not</emphasis> the model backing the tree view to which this cell 
-   * renderer is attached.
+   * <emphasis>not</emphasis> the model backing the tree view to which 
+   * this cell renderer is attached.
    * 
-   * #GtkCellRendererCombo automatically adds a text cell renderer for this column
-   * to its combo box.
+   * #GtkCellRendererCombo automatically adds a text cell renderer for 
+   * this column to its combo box.
    *
    * Since: 2.6
    */
@@ -117,8 +119,8 @@ gtk_cell_renderer_combo_class_init (GtkCellRendererComboClass *klass)
   /** 
    * GtkCellRendererCombo:has-entry:
    *
-   * If  %TRUE, the cell renderer will include an entry and allow to enter values 
-   * other than the ones in the popup list. 
+   * If %TRUE, the cell renderer will include an entry and allow to enter 
+   * values other than the ones in the popup list. 
    *
    * Since: 2.6
    */
diff --git a/gtk/gtkcellrenderertext.c b/gtk/gtkcellrenderertext.c
index cad230b2c1..e65057dcef 100644
--- a/gtk/gtkcellrenderertext.c
+++ b/gtk/gtkcellrenderertext.c
@@ -562,11 +562,14 @@ gtk_cell_renderer_text_class_init (GtkCellRendererTextClass *class)
 
   /**
    * GtkCellRendererText::edited
-   * @renderer: the object which received the signal.
-   * @path: the path identifying the edited cell.
-   * @new_text: the new text.
+   * @renderer: the object which received the signal
+   * @path: the path identifying the edited cell
+   * @new_text: the new text
    *
    * This signal is emitted after @renderer has been edited.
+   *
+   * It is the responsibility of the application to update the model
+   * and store @new_text at the position indicated by @path.
    */
   text_cell_renderer_signals [EDITED] =
     g_signal_new (I_("edited"),