Some doc updates

svn path=/trunk/; revision=18089

ChangeLog

@@ -1,3 +1,10 @@
+2007-06-09  Matthias Clasen  <mclasen@redhat.com>
+
+	* gtk/gtkbox.c: Move docs inline.
+
+	* gtk/gtkrange.c:
+	* gtk/gtkscale.c: Doc formatting improvements.
+
 2007-06-09  Matthias Clasen  <mclasen@redhat.com>
 
 	* gtk/gtkscalebutton.c: Add an icons property, make 

docs/reference/ChangeLog

@@ -1,3 +1,7 @@
+2007-06-09  Matthias Clasen  <mclasen@redhat.com>
+
+	* gtk/tmpl/gtkbox.sgml: Move docs inline
+
 2007-06-08  Matthias Clasen  <mclasen@redhat.com>
 
 	* gtk/gtk-sections.txt: Add gtk_rc_parse_color_full

docs/reference/gtk/tmpl/gtkbox.sgml

@@ -6,7 +6,7 @@ Base class for box containers
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-GtkBox is an abstract widget which encapsulates functionallity for a
+GtkBox is an abstract widget which encapsulates functionality for a
 particular kind of container, one that organizes a variable number of
 widgets into a rectangular area.  GtkBox currently has two derived
 classes, #GtkHBox and #GtkVBox.
@@ -22,8 +22,8 @@ row, or the width of a column.
 GtkBox uses a notion of <emphasis>packing</emphasis>.  Packing refers to
 adding widgets with reference to a particular position in a
 #GtkContainer.  For a GtkBox, there are two reference positions: the
-<emphasis>start</emphasis> and the <emphasis>end</emphasis> of the box.  For a
+<emphasis>start</emphasis> and the <emphasis>end</emphasis> of the box.  
-#GtkVBox, the start is defined as the top of the box and the end is
+For a #GtkVBox, the start is defined as the top of the box and the end is
 defined as the bottom.  For a #GtkHBox the start is defined as the
 left side and the end is defined as the right side.
 </para>
@@ -36,9 +36,8 @@ both ends of the same GtkBox.
 <para>
 Use gtk_box_pack_start_defaults() or gtk_box_pack_end_defaults()
 to pack widgets into a GtkBox if you do not need to specify the
-<structfield>expand</structfield>, <structfield>fill</structfield>, or
+#GtkBox:expand, #GtkBox:fill, or #GtkBox:padding child properties 
-<structfield>padding</structfield> attributes of the child to be
+for the child to be added.
-added.
 </para>
 <para>
 Because GtkBox is a #GtkContainer, you may also use
@@ -59,9 +58,8 @@ Use gtk_box_reorder_child() to move a GtkBox child to a different
 place in the box.
 </para>
 <para>
-Use gtk_box_set_child_packing() to reset the
+Use gtk_box_set_child_packing() to reset the #GtkBox:expand, 
-<structfield>expand</structfield>, <structfield>fill</structfield>,
+#GtkBox:fill and #GtkBox:padding child properties.
-and <structfield>padding</structfield> attributes of any GtkBox child.
 Use gtk_box_query_child_packing() to query these fields.
 </para>
 
@@ -105,38 +103,18 @@ layouts.</para></listitem>
 
 <!-- ##### STRUCT GtkBox ##### -->
 <para>
-The #GtkBox-struct describes an instance of GtkBox and contains the following fields.
+The #GtkBox-struct describes an instance of GtkBox and contains the 
-(These fields should be considered read-only. They should never be set by
+following fields.  (These fields should be considered read-only. 
-an application.)
+They should never be set by an application.)
-
-<informaltable pgwide="1" frame="none" role="struct">
-<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
-<tbody>
-
-<row>
-<entry>#GList * <structfield>children</structfield>;</entry>
-<entry>a list of children belonging the GtkBox.  The data is a list of
-structures of type #GtkBoxChild-struct.</entry>
-</row>
-
-<row>
-<entry>#gint16 <structfield>spacing</structfield>;</entry>
-<entry>the number of pixels to put between children of the GtkBox, zero
-by default.  Use gtk_box_set_spacing() to set this field.</entry>
-</row>
-
-<row>
-<entry>#guint <structfield>homogeneous</structfield>;</entry>
-<entry>a flag that if %TRUE forces all children to get equal space in
-the GtkBox; %FALSE by default.  Use gtk_box_set_homogeneous() to set this
-field.</entry>
-</row>
-</tbody></tgroup></informaltable>
 </para>
 
-@children: 
+@children: a list of children belonging the GtkBox.  
-@spacing: 
+  The data is a list of structures of type #GtkBoxChild-struct.
-@homogeneous: 
+@spacing: the number of pixels to put between children of the GtkBox, 
+  zero by default. Use gtk_box_set_spacing() to set this field.
+@homogeneous: a flag that if %TRUE forces all children to get equal 
+  space in the GtkBox; %FALSE by default. Use gtk_box_set_homogeneous() 
+  to set this field.
 
 <!-- ##### ARG GtkBox:homogeneous ##### -->
 <para>
@@ -186,133 +164,65 @@ and <structfield>pack</structfield> fields.
 #GtkBoxChild-struct contains the following fields.  (These fields
 should be considered read-only. They should never be directly set by an
 application.)
-
-<informaltable pgwide="1" frame="none" role="struct">
-<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
-<tbody>
-
-<row>
-<entry>#GtkWidget * <structfield>widget</structfield>;</entry>
-<entry>the child widget, packed into the GtkBox.</entry>
-</row>
-
-<row>
-<entry>#guint16 <structfield>padding</structfield>;</entry>
-<entry>the number of extra pixels to put between this child and its
-neighbors, set when packed, zero by default.</entry>
-</row>
-
-<row>
-<entry>#guint <structfield>expand</structfield>;</entry>
-<entry>flag indicates whether extra space should be given to this
-child.  Any extra space given to the parent GtkBox is divided up among
-all children with this attribute set to %TRUE; set when packed, %TRUE by
-default.</entry>
-</row>
-
-<row>
-<entry>#guint <structfield>fill</structfield>;</entry>
-<entry>flag indicates whether any extra space given to this child due to its
-<structfield>expand</structfield> attribute being set is actually
-allocated to the child, rather than being used as padding
-around the widget; set when packed, %TRUE by default.</entry>
-</row>
-
-<row>
-<entry>#guint <structfield>pack</structfield>;</entry> <entry>one of
-#GtkPackType indicating whether the child is packed with reference to
-the start (top/left) or end (bottom/right) of the GtkBox.</entry>
-</row>
-</tbody></tgroup></informaltable>
 </para>
 
-@widget: 
+@widget: the child widget, packed into the GtkBox.
-@padding: 
+@padding: the number of extra pixels to put between this child and its
-@expand: 
+  neighbors, set when packed, zero by default.
-@fill: 
+@expand: flag indicates whether extra space should be given to this
-@pack: 
+  child. Any extra space given to the parent GtkBox is divided up 
+  among all children with this attribute set to %TRUE; set when packed, 
+  %TRUE by default.
+@fill: flag indicates whether any extra space given to this child due 
+  to its @expand attribute being set is actually allocated to the child, 
+  rather than being used as padding around the widget; set when packed, 
+  %TRUE by default.
+@pack: one of #GtkPackType indicating whether the child is packed with 
+  reference to the start (top/left) or end (bottom/right) of the GtkBox.
 @is_secondary: 
 
+
 <!-- ##### FUNCTION gtk_box_pack_start ##### -->
 <para>
-Adds @child to @box, packed with reference to the start of @box.  The
+
-@child is packed after any other child packed with reference to the
-start of @box.
 </para>
 
-@box: a #GtkBox.
+@box: 
-@child: the #GtkWidget to be added to @box.
+@child:
-@expand: %TRUE if the new child is to be given extra space allocated to
+@expand:
-@box.  The extra space will be divided evenly between all children of
+@box 
-@box that use this option.
+@fill:
-@fill: %TRUE if space given to @child by the @expand option is
+@padding: 
-actually allocated to @child, rather than just padding it.  This
-parameter has no effect if @expand is set to %FALSE.  A child is
-always allocated the full height of a #GtkHBox and the full width of a
-#GtkVBox.  This option affects the other dimension.
-@padding: extra space in pixels to put between this child and its
-neighbors, over and above the global amount specified by
-<structfield>spacing</structfield> in #GtkBox-struct.  If @child is a
-widget at one of the reference ends of @box, then @padding pixels are also put
-between @child and the reference edge of @box.
 
 
 <!-- ##### FUNCTION gtk_box_pack_end ##### -->
 <para>
-Adds @child to @box, packed with reference to the end of @box.  The
+
-@child is packed after (away from end of) any other child packed with reference to the
-end of @box.
 </para>
 
-@box: a #GtkBox.
+@box: 
-@child: the #GtkWidget to be added to @box.
+@child: 
-@expand: %TRUE if the new child is to be given extra space allocated to
+@expand: 
-@box.  The extra space will be divided evenly between all children of
+@fill: 
-@box that use this option.
+@padding: 
-@fill: %TRUE if space given to @child by the @expand option is
-actually allocated to @child, rather than just padding it.  This
-parameter has no effect if @expand is set to %FALSE.  A child is
-always allocated the full height of a #GtkHBox and the full width of a
-#GtkVBox.  This option affects the other dimension.
-@padding: extra space in pixels to put between this child and its
-neighbors, over and above the global amount specified by
-<structfield>spacing</structfield> in #GtkBox-struct.  If @child is a
-widget at one of the reference ends of @box, then @padding pixels are also put
-between @child and the reference edge of @box.
 
 
 <!-- ##### FUNCTION gtk_box_pack_start_defaults ##### -->
 <para>
-Adds @widget to @box, packed with reference to the start of @box.  The
+
-child is packed after any other child packed with reference to the
-start of @box.
-</para>
-<para>
-Parameters for how to pack the child @widget,
-<structfield>expand</structfield>, <structfield>fill</structfield>,
-and <structfield>padding</structfield> in #GtkBoxChild-struct, are given their default
-values, %TRUE, %TRUE, and 0, respectively.
 </para>
 
-@box: a #GtkBox.
+@box: 
-@widget: the #GtkWidget to be added to @box.
+@widget: 
 
 
 <!-- ##### FUNCTION gtk_box_pack_end_defaults ##### -->
 <para>
-Adds @widget to @box, packed with reference to the end of @box.  The
+
-child is packed after (away from end of) any other child packed with
-reference to the end of @box.
-</para>
-<para>
-Parameters for how to pack the child @widget,
-<structfield>expand</structfield>, <structfield>fill</structfield>,
-and <structfield>padding</structfield> in #GtkBoxChild-struct, are given their default
-values, %TRUE, %TRUE, and 0, respectively.
 </para>
 
-@box: a #GtkBox.
+@box: 
-@widget: the #GtkWidget to be added to @box.
+@widget:
 
 
 <!-- ##### FUNCTION gtk_box_get_homogeneous ##### -->
@@ -326,14 +236,11 @@ values, %TRUE, %TRUE, and 0, respectively.
 
 <!-- ##### FUNCTION gtk_box_set_homogeneous ##### -->
 <para>
-Sets the <structfield>homogeneous</structfield> field of
+
-#GtkBox-struct, controlling whether or not all children of @box are
-given equal space in the box.
 </para>
 
-@box: a #GtkBox.
+@box: 
-@homogeneous: a boolean value, %TRUE to create equal allotments,
+@homogeneous: 
-%FALSE for variable allotments.
 
 
 <!-- ##### FUNCTION gtk_box_get_spacing ##### -->
@@ -347,67 +254,44 @@ given equal space in the box.
 
 <!-- ##### FUNCTION gtk_box_set_spacing ##### -->
 <para>
-Sets the <structfield>spacing</structfield> field of #GtkBox-struct,
+
-which is the number of pixels to place between children of @box.
 </para>
 
-@box: a #GtkBox.
+@box: 
-@spacing: the number of pixels to put between children.
+@spacing: 
 
 
 <!-- ##### FUNCTION gtk_box_reorder_child ##### -->
 <para>
-Moves @child to a new @position in the list of @box children.  The
+
-list is the <structfield>children</structfield> field of
-#GtkBox-struct, and contains both widgets packed #GTK_PACK_START as
-well as widgets packed #GTK_PACK_END, in the order that these widgets
-were added to @box.
-</para>
-<para>
-A widget's position in the @box children list determines where the
-widget is packed into @box.  A child widget at some position in the
-list will be packed just after all other widgets of the same packing
-type that appear earlier in the list.
 </para>
 
-@box: a #GtkBox.
+@box: 
-@child: the #GtkWidget to move.
+@child:
-@position: the new position for @child in the
+@position:
-<structfield>children</structfield> list of #GtkBox-struct, starting
-from 0. If negative, indicates the end of the list.
 
 
 <!-- ##### FUNCTION gtk_box_query_child_packing ##### -->
 <para>
-Returns information about how @child is packed into @box.
+
 </para>
 
-@box: a #GtkBox.
+@box:
-@child: the #GtkWidget of the child to query.
+@child:
-@expand: the returned value of the <structfield>expand</structfield>
+@expand:
-field in #GtkBoxChild-struct.
+@fill: 
-@fill: the returned value of the <structfield>fill</structfield> field
+@padding:
-in #GtkBoxChild-struct.
+@pack_type: 
-@padding: the returned value of the <structfield>padding</structfield>
-field in #GtkBoxChild-struct.
-@pack_type: the returned value of the <structfield>pack</structfield>
-field in #GtkBoxChild-struct.
 
 
 <!-- ##### FUNCTION gtk_box_set_child_packing ##### -->
 <para>
-Sets the way @child is packed into @box.
+
 </para>
 
-@box: a #GtkBox.
+@box: 
-@child: the #GtkWidget of the child to set.
+@child: 
-@expand: the new value of the <structfield>expand</structfield> field
+@expand:
-in #GtkBoxChild-struct.
+@fill: 
-@fill: the new value of the <structfield>fill</structfield> field in
+@padding:
-#GtkBoxChild-struct.
+@pack_type:
-@padding: the new value of the <structfield>padding</structfield>
-field in #GtkBoxChild-struct.
-@pack_type: the new value of the <structfield>pack</structfield> field
-in #GtkBoxChild-struct.
-
-

gtk/gtkbox.c

@@ -329,6 +329,28 @@ gtk_box_get_child_property (GtkContainer *container,
     }
 }
 
+/**
+ * gtk_box_pack_start:
+ * @box: a #GtkBox
+ * @child: the #GtkWidget to be added to @box
+ * @expand: %TRUE if the new child is to be given extra space allocated to
+ * @box.  The extra space will be divided evenly between all children of
+ * @box that use this option
+ * @fill: %TRUE if space given to @child by the @expand option is
+ *   actually allocated to @child, rather than just padding it.  This
+ *   parameter has no effect if @expand is set to %FALSE.  A child is
+ *   always allocated the full height of a #GtkHBox and the full width 
+ *   of a #GtkVBox. This option affects the other dimension
+ * @padding: extra space in pixels to put between this child and its
+ *   neighbors, over and above the global amount specified by
+ *   #GtkBox:spacing property.  If @child is a widget at one of the 
+ *   reference ends of @box, then @padding pixels are also put between 
+ *   @child and the reference edge of @box
+ *
+ * Adds @child to @box, packed with reference to the start of @box.
+ * The @child is packed after any other child packed with reference 
+ * to the start of @box.
+ */
 void
 gtk_box_pack_start (GtkBox    *box,
 		    GtkWidget *child,
@@ -364,6 +386,28 @@ gtk_box_pack_start (GtkBox    *box,
   gtk_widget_thaw_child_notify (child);
 }
 
+/**
+ * gtk_box_pack_end:
+ * @box: a #GtkBox
+ * @child: the #GtkWidget to be added to @box
+ * @expand: %TRUE if the new child is to be given extra space allocated 
+ *   to @box. The extra space will be divided evenly between all children 
+ *   of @box that use this option
+ * @fill: %TRUE if space given to @child by the @expand option is
+ *   actually allocated to @child, rather than just padding it.  This
+ *   parameter has no effect if @expand is set to %FALSE.  A child is
+ *   always allocated the full height of a #GtkHBox and the full width 
+ *   of a #GtkVBox.  This option affects the other dimension
+ * @padding: extra space in pixels to put between this child and its
+ *   neighbors, over and above the global amount specified by
+ *   #GtkBox:spacing property.  If @child is a widget at one of the 
+ *   reference ends of @box, then @padding pixels are also put between 
+ *   @child and the reference edge of @box
+ *
+ * Adds @child to @box, packed with reference to the end of @box.  
+ * The @child is packed after (away from end of) any other child 
+ * packed with reference to the end of @box.
+ */
 void
 gtk_box_pack_end (GtkBox    *box,
 		  GtkWidget *child,
@@ -399,6 +443,19 @@ gtk_box_pack_end (GtkBox    *box,
   gtk_widget_thaw_child_notify (child);
 }
 
+/**
+ * gtk_box_pack_start_defaults:
+ * @box: a #GtkBox
+ * @widget: the #GtkWidget to be added to @box
+ *
+ * Adds @widget to @box, packed with reference to the start of @box.
+ * The child is packed after any other child packed with reference 
+ * to the start of @box. 
+ * 
+ * Parameters for how to pack the child @widget, #GtkBox:expand, 
+ * #GtkBox:fill and #GtkBox:padding, are given their default
+ * values, %TRUE, %TRUE, and 0, respectively.
+ */
 void
 gtk_box_pack_start_defaults (GtkBox    *box,
 			     GtkWidget *child)
@@ -406,6 +463,19 @@ gtk_box_pack_start_defaults (GtkBox    *box,
   gtk_box_pack_start (box, child, TRUE, TRUE, 0);
 }
 
+/**
+ * gtk_box_pack_end_defaults:
+ * @box: a #GtkBox
+ * @widget: the #GtkWidget to be added to @box
+ *
+ * Adds @widget to @box, packed with reference to the end of @box.
+ * The child is packed after any other child packed with reference 
+ * to the start of @box. 
+ * 
+ * Parameters for how to pack the child @widget, #GtkBox:expand, 
+ * #GtkBox:fill and #GtkBox:padding, are given their default
+ * values, %TRUE, %TRUE, and 0, respectively.
+ */
 void
 gtk_box_pack_end_defaults (GtkBox    *box,
 			   GtkWidget *child)
@@ -413,6 +483,16 @@ gtk_box_pack_end_defaults (GtkBox    *box,
   gtk_box_pack_end (box, child, TRUE, TRUE, 0);
 }
 
+/**
+ * gtk_box_set_homogeneous:
+ * @box: a #GtkBox
+ * @homogeneous: a boolean value, %TRUE to create equal allotments,
+ *   %FALSE for variable allotments
+ * 
+ * Sets the #GtkBox:homogeneous property of @box, controlling 
+ * whether or not all children of @box are given equal space 
+ * in the box.
+ */
 void
 gtk_box_set_homogeneous (GtkBox  *box,
 			 gboolean homogeneous)
@@ -444,6 +524,14 @@ gtk_box_get_homogeneous (GtkBox *box)
   return box->homogeneous;
 }
 
+/**
+ * gtk_box_set_spacing:
+ * @box: a #GtkBox
+ * @spacing: the number of pixels to put between children
+ *
+ * Sets the #GtkBox:spacing property of @box, which is the 
+ * number of pixels to place between children of @box.
+ */
 void
 gtk_box_set_spacing (GtkBox *box,
 		     gint    spacing)
@@ -474,6 +562,25 @@ gtk_box_get_spacing (GtkBox *box)
   return box->spacing;
 }
 
+/**
+ * gtk_box_reorder_child:
+ * @box: a #GtkBox
+ * @child: the #GtkWidget to move
+ * @position: the new position for @child in the list of children 
+ *   of @box, starting from 0. If negative, indicates the end of 
+ *   the list
+ *
+ * Moves @child to a new @position in the list of @box children.  
+ * The list is the <structfield>children</structfield> field of
+ * #GtkBox-struct, and contains both widgets packed #GTK_PACK_START 
+ * as well as widgets packed #GTK_PACK_END, in the order that these 
+ * widgets were added to @box.
+ * 
+ * A widget's position in the @box children list determines where 
+ * the widget is packed into @box.  A child widget at some position 
+ * in the list will be packed just after all other widgets of the 
+ * same packing type that appear earlier in the list.
+ */ 
 void
 gtk_box_reorder_child (GtkBox    *box,
 		       GtkWidget *child,
@@ -518,6 +625,17 @@ gtk_box_reorder_child (GtkBox    *box,
     gtk_widget_queue_resize (child);
 }
 
+/**
+ * gtk_box_query_child_packing:
+ * @box: a #GtkBox
+ * @child: the #GtkWidget of the child to query
+ * @expand: pointer to return location for #GtkBox:expand child property 
+ * @fill: pointer to return location for #GtkBox:fill child property 
+ * @padding: pointer to return location for #GtkBox:padding child property 
+ * @pack_type: pointer to return location for #GtkBox:pack-type child property 
+ *
+ * Returns information about how @child is packed into @box.
+ */
 void
 gtk_box_query_child_packing (GtkBox      *box,
 			     GtkWidget   *child,
@@ -555,6 +673,17 @@ gtk_box_query_child_packing (GtkBox             *box,
     }
 }
 
+/**
+ * gtk_box_set_child_packing:
+ * @box: a #GtkBox
+ * @child: the #GtkWidget of the child to set
+ * @expand: the new value of the #GtkBox:expand child property 
+ * @fill: the new value of the #GtkBox:fill child property
+ * @padding: the new value of the #GtkBox:padding child property
+ * @pack_type: the new value of the #GtkBox:pack-type child property
+ *
+ * Sets the way @child is packed into @box.
+ */
 void
 gtk_box_set_child_packing (GtkBox      *box,
 			   GtkWidget   *child,

gtk/gtkrange.c

@@ -282,11 +282,11 @@ gtk_range_class_init (GtkRangeClass *class)
 
   /**
    * GtkRange::change-value:
-   * @range: the range that received the signal.
+   * @range: the range that received the signal
-   * @scroll: the type of scroll action that was performed.
+   * @scroll: the type of scroll action that was performed
-   * @value: the new value resulting from the scroll action.
+   * @value: the new value resulting from the scroll action
    * @returns: %TRUE to prevent other handlers from being invoked for the
-   * signal.  %FALSE to propagate the signal further.
+   * signal, %FALSE to propagate the signal further
    *
    * The ::change-value signal is emitted when a scroll action is
    * performed on a range.  It allows an application to determine the
@@ -363,7 +363,7 @@ gtk_range_class_init (GtkRangeClass *class)
   /**
    * GtkRange:show-fill-level:
    *
-   * The show-fill-level property controls wether fill level indicator
+   * The show-fill-level property controls whether fill level indicator
    * graphics are displayed on the trough. See
    * gtk_range_set_show_fill_level().
    *
@@ -380,9 +380,9 @@ gtk_range_class_init (GtkRangeClass *class)
   /**
    * GtkRange:restrict-to-fill-level:
    *
-   * The restrict-to-fill-level proeprty controls whether slider
+   * The restrict-to-fill-level property controls whether slider
    * movement is restricted to an upper boundary set by the
-   * fill-level. See gtk_range_set_restrict_to_fill_level().
+   * fill level. See gtk_range_set_restrict_to_fill_level().
    *
    * Since: 2.12
    **/
@@ -441,7 +441,7 @@ gtk_range_class_init (GtkRangeClass *class)
    *
    * The spacing between the stepper buttons and thumb. Note that
    * setting this value to anything > 0 will automatically set the
-   * trough-under-steppers style property to TRUE as well. Also,
+   * trough-under-steppers style property to %TRUE as well. Also,
    * stepper-spacing won't have any effect if there are no steppers.
    */
   gtk_widget_class_install_style_property (widget_class,
@@ -479,6 +479,9 @@ gtk_range_class_init (GtkRangeClass *class)
   /**
    * GtkRange:trough-side-details:
    *
+   * When %TRUE, the parts of the trough on the two sides of the 
+   * slider are drawn with different details.
+   *
    * Since: 2.10
    */
   gtk_widget_class_install_style_property (widget_class,
@@ -493,7 +496,7 @@ gtk_range_class_init (GtkRangeClass *class)
    *
    * Whether to draw the trough across the full length of the range or
    * to exclude the steppers and their spacing. Note that setting the
-   * stepper-spacing style property to any value > 0 will
+   * #GtkRange:stepper-spacing style property to any value > 0 will
    * automatically enable trough-under-steppers too.
    *
    * Since: 2.10
@@ -659,7 +662,6 @@ gtk_range_get_adjustment (GtkRange *range)
  * continuous. #GTK_UPDATE_DISCONTINUOUS means that the value will only
  * be updated when the user releases the button and ends the slider
  * drag operation.
- * 
  **/
 void
 gtk_range_set_update_policy (GtkRange      *range,
@@ -702,7 +704,6 @@ gtk_range_get_update_policy (GtkRange *range)
  * is normally 0 for #GtkScale and nonzero for #GtkScrollbar, and
  * indicates the size of the visible area of the widget being scrolled.
  * The page size affects the size of the scrollbar slider.
- * 
  **/
 void
 gtk_range_set_adjustment (GtkRange      *range,
@@ -752,7 +753,6 @@ gtk_range_set_adjustment (GtkRange      *range,
  * slider moves from top to bottom or left to right. Inverted
  * ranges have higher values at the top or on the right rather than
  * on the bottom or left.
- * 
  **/
 void
 gtk_range_set_inverted (GtkRange *range,
@@ -890,7 +890,6 @@ gtk_range_get_upper_stepper_sensitivity (GtkRange *range)
  * The step size is used when the user clicks the #GtkScrollbar
  * arrows or moves #GtkScale via arrow keys. The page size
  * is used for example when moving via Page Up or Page Down keys.
- * 
  **/
 void
 gtk_range_set_increments (GtkRange *range,
@@ -948,9 +947,8 @@ gtk_range_set_range (GtkRange *range,
  *
  * Sets the current value of the range; if the value is outside the
  * minimum or maximum range values, it will be clamped to fit inside
- * them. The range emits the "value_changed" signal if the value
+ * them. The range emits the #GtkRange::value-changed signal if the 
- * changes.
+ * value changes.
- * 
  **/
 void
 gtk_range_set_value (GtkRange *range,

gtk/gtkscale.c

@@ -595,8 +595,8 @@ gtk_scale_screen_changed (GtkWidget *widget,
  * @scale: a #GtkScale
  * @value: adjustment value
  * 
- * Emits "format_value" signal to format the value, if no user
+ * Emits #GtkScale::format-value signal to format the value, 
- * signal handlers, falls back to a default format.
+ * if no user signal handlers, falls back to a default format.
  * 
  * Return value: formatted value
  **/
@@ -637,11 +637,12 @@ gtk_scale_finalize (GObject *object)
  * gtk_scale_get_layout:
  * @scale: A #GtkScale
  *
- * Gets the #PangoLayout used to display the scale. The returned object
+ * Gets the #PangoLayout used to display the scale. 
- * is owned by the scale so does not need to be freed by the caller. 
+ * The returned object is owned by the scale so does 
+ * not need to be freed by the caller. 
  *
- * Return value: the #PangoLayout for this scale, or %NULL if the draw_value property
+ * Return value: the #PangoLayout for this scale, or %NULL 
- *    is %FALSE.
+ *    if the #GtkScale:draw-value property is %FALSE.
  *   
  * Since: 2.4
  **/
@@ -676,13 +677,13 @@ gtk_scale_get_layout (GtkScale *scale)
  * @x: location to store X offset of layout, or %NULL
  * @y: location to store Y offset of layout, or %NULL
  *
- * Obtains the coordinates where the scale will draw the #PangoLayout
+ * Obtains the coordinates where the scale will draw the 
- * representing the text in the scale. Remember
+ * #PangoLayout representing the text in the scale. Remember
  * when using the #PangoLayout function you need to convert to
  * and from pixels using PANGO_PIXELS() or #PANGO_SCALE. 
  *
- * If the draw_value property is %FALSE, the return values are 
+ * If the #GtkScale:draw-value property is %FALSE, the return 
- * undefined.
+ * values are undefined.
  *
  * Since: 2.4
  **/