gtkadjustment: Move documentation to inline comments

diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore
index 1f16d5c8203b5c3a7f04f831c38dcff5e4ac94cc..6e3e3a0331c7cab0929f250a0a47d9d8aabdfed3 100644 (file)
--- a/docs/reference/gtk/tmpl/.gitignore
+++ b/docs/reference/gtk/tmpl/.gitignore
@@ -1,6 +1,7 @@
 gtkaccelmap.sgml
 gtkactiongroup.sgml
 gtkaboutdialog.sgml
+gtkadjustment.sgml
 gtkbbox.sgml
 gtkbox.sgml
 gtkbuilder.sgml

diff --git a/docs/reference/gtk/tmpl/gtkadjustment.sgml b/docs/reference/gtk/tmpl/gtkadjustment.sgml
deleted file mode 100644 (file)
index f41c2b3..0000000
--- a/docs/reference/gtk/tmpl/gtkadjustment.sgml
+++ /dev/null
@@ -1,310 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-GtkAdjustment
-
-<!-- ##### SECTION Short_Description ##### -->
-A representation of an adjustable bounded value
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-The #GtkAdjustment object represents a value which has an associated lower
-and upper bound, together with step and page increments, and a page size.
-It is used within several GTK+ widgets, including
-#GtkSpinButton, #GtkViewport, and #GtkRange (which is a base class for
-#GtkHScrollbar, #GtkVScrollbar, #GtkHScale, and #GtkVScale).
-</para>
-<para>
-The #GtkAdjustment object does not update the value itself. Instead
-it is left up to the owner of the #GtkAdjustment to control the value.
-</para>
-<para>
-The owner of the #GtkAdjustment typically calls the
-gtk_adjustment_value_changed() and gtk_adjustment_changed() functions
-after changing the value and its bounds. This results in the emission of the
-&quot;value_changed&quot; or &quot;changed&quot; signal respectively.
-</para>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### SECTION Image ##### -->
-
-
-<!-- ##### STRUCT GtkAdjustment ##### -->
-<para>
-The #GtkAdjustment-struct struct contains the following fields.
-
-<informaltable pgwide="1" frame="none" role="struct">
-<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
-<tbody>
-
-<row>
-<entry>#gdouble lower;</entry>
-<entry>the minimum value.</entry>
-</row>
-
-<row>
-<entry>#gdouble upper;</entry>
-<entry>the maximum value.</entry>
-</row>
-
-<row>
-<entry>#gdouble value;</entry>
-<entry>the current value.</entry>
-</row>
-
-<row>
-<entry>#gdouble step_increment;</entry>
-<entry>the increment to use to make minor changes to the value.
-In a #GtkScrollbar this increment is used when the mouse is clicked on the
-arrows at the top and bottom of the scrollbar, to scroll by a small amount.
-</entry>
-</row>
-
-<row>
-<entry>#gdouble page_increment;</entry>
-<entry>the increment to use to make major changes to the value.
-In a #GtkScrollbar this increment is used when the mouse is clicked in the
-trough, to scroll by a large amount.
-</entry>
-</row>
-
-<row>
-<entry>#gdouble page_size;</entry>
-<entry>the page size.
-In a #GtkScrollbar this is the size of the area which is currently visible.
-</entry>
-</row>
-
-</tbody></tgroup></informaltable>
-
-</para>
-
-
-<!-- ##### SIGNAL GtkAdjustment::changed ##### -->
-<para>
-Emitted when one or more of the #GtkAdjustment fields have been changed,
-other than the value field.
-</para>
-
-@adjustment: the object which received the signal.
-
-<!-- ##### SIGNAL GtkAdjustment::value-changed ##### -->
-<para>
-Emitted when the #GtkAdjustment value field has been changed.
-</para>
-
-@adjustment: the object which received the signal.
-
-<!-- ##### ARG GtkAdjustment:lower ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkAdjustment:page-increment ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkAdjustment:page-size ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkAdjustment:step-increment ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkAdjustment:upper ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkAdjustment:value ##### -->
-<para>
-
-</para>
-
-<!-- ##### FUNCTION gtk_adjustment_new ##### -->
-<para>
-Creates a new #GtkAdjustment.
-</para>
-
-@value: the initial value.
-@lower: the minimum value.
-@upper: the maximum value.
-@step_increment: the step increment.
-@page_increment: the page increment.
-@page_size: the page size.
-@Returns: a new #GtkAdjustment.
-
-
-<!-- ##### FUNCTION gtk_adjustment_get_value ##### -->
-<para>
-
-</para>
-
-@adjustment: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_adjustment_set_value ##### -->
-<para>
-Sets the #GtkAdjustment value. The value is clamped to lie between
-<literal>adjustment-&gt;lower</literal> and
-<literal>adjustment-&gt;upper</literal>.
-</para>
-<para>
-Note that for adjustments which are used in a #GtkScrollbar, the effective
-range of allowed values goes from <literal>adjustment-&gt;lower</literal> to
-<literal>adjustment-&gt;upper - adjustment-&gt;page_size</literal>.
-</para>
-
-@adjustment: a #GtkAdjustment.
-@value: the new value.
-
-
-<!-- ##### FUNCTION gtk_adjustment_clamp_page ##### -->
-<para>
-Updates the #GtkAdjustment @value to ensure that the range between @lower
-and @upper is in the current page (i.e. between @value and @value +
-@page_size).
-If the range is larger than the page size, then only the start of it will
-be in the current page.
-A &quot;changed&quot; signal will be emitted if the value is changed.
-</para>
-
-@adjustment: a #GtkAdjustment.
-@lower: the lower value.
-@upper: the upper value.
-
-
-<!-- ##### FUNCTION gtk_adjustment_changed ##### -->
-<para>
-Emits a &quot;changed&quot; signal from the #GtkAdjustment.
-This is typically called by the owner of the #GtkAdjustment after it has
-changed any of the #GtkAdjustment fields other than the value.
-</para>
-
-@adjustment: a #GtkAdjustment
-
-
-<!-- ##### FUNCTION gtk_adjustment_value_changed ##### -->
-<para>
-Emits a &quot;value_changed&quot; signal from the #GtkAdjustment.
-This is typically called by the owner of the #GtkAdjustment after it has
-changed the #GtkAdjustment value field.
-</para>
-
-@adjustment: a #GtkAdjustment
-
-
-<!-- ##### FUNCTION gtk_adjustment_configure ##### -->
-<para>
-
-</para>
-
-@adjustment: 
-@value: 
-@lower: 
-@upper: 
-@step_increment: 
-@page_increment: 
-@page_size: 
-
-
-<!-- ##### FUNCTION gtk_adjustment_get_lower ##### -->
-<para>
-
-</para>
-
-@adjustment: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_adjustment_get_page_increment ##### -->
-<para>
-
-</para>
-
-@adjustment: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_adjustment_get_page_size ##### -->
-<para>
-
-</para>
-
-@adjustment: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_adjustment_get_step_increment ##### -->
-<para>
-
-</para>
-
-@adjustment: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_adjustment_get_upper ##### -->
-<para>
-
-</para>
-
-@adjustment: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_adjustment_set_lower ##### -->
-<para>
-
-</para>
-
-@adjustment: 
-@lower: 
-
-
-<!-- ##### FUNCTION gtk_adjustment_set_page_increment ##### -->
-<para>
-
-</para>
-
-@adjustment: 
-@page_increment: 
-
-
-<!-- ##### FUNCTION gtk_adjustment_set_page_size ##### -->
-<para>
-
-</para>
-
-@adjustment: 
-@page_size: 
-
-
-<!-- ##### FUNCTION gtk_adjustment_set_step_increment ##### -->
-<para>
-
-</para>
-
-@adjustment: 
-@step_increment: 
-
-
-<!-- ##### FUNCTION gtk_adjustment_set_upper ##### -->
-<para>
-
-</para>
-
-@adjustment: 
-@upper: 
-
-

diff --git a/gtk/gtkadjustment.c b/gtk/gtkadjustment.c
index 9c3b1d36dded62e9502f1559af60daa364f784d8..ae5e2926b2e94ddbf4ab91c475d9eb2d459538f1 100644 (file)
--- a/gtk/gtkadjustment.c
+++ b/gtk/gtkadjustment.c
@@ -31,6 +31,27 @@
 #include "gtkintl.h"
 
 
+/**
+ * SECTION:gtkadjustment
+ * @Short_description: A representation of an adjustable bounded value
+ * @Title: GtkAdjustment
+ *
+ * The #GtkAdjustment object represents a value which has an associated lower
+ * and upper bound, together with step and page increments, and a page size.
+ * It is used within several GTK+ widgets, including
+ * #GtkSpinButton, #GtkViewport, and #GtkRange (which is a base class for
+ * #GtkHScrollbar, #GtkVScrollbar, #GtkHScale, and #GtkVScale).
+ *
+ * The #GtkAdjustment object does not update the value itself. Instead
+ * it is left up to the owner of the #GtkAdjustment to control the value.
+ *
+ * The owner of the #GtkAdjustment typically calls the
+ * gtk_adjustment_value_changed() and gtk_adjustment_changed() functions
+ * after changing the value and its bounds. This results in the emission of the
+ * #GtkAdjustment::value_changed or #GtkAdjustment::changed signal respectively.
+ */
+
+
 enum
 {
   PROP_0,
@@ -188,6 +209,13 @@ gtk_adjustment_class_init (GtkAdjustmentClass *class)
                                                        0.0, 
                                                        GTK_PARAM_READWRITE));
 
+  /**
+   * GtkAdjustment::changed:
+   * @adjustment: the object which received the signal.
+   *
+   * Emitted when one or more of the #GtkAdjustment fields have been changed,
+   * other than the value field.
+   */
   adjustment_signals[CHANGED] =
     g_signal_new (I_("changed"),
                  G_OBJECT_CLASS_TYPE (class),
@@ -197,6 +225,12 @@ gtk_adjustment_class_init (GtkAdjustmentClass *class)
                  _gtk_marshal_VOID__VOID,
                  G_TYPE_NONE, 0);
 
+  /**
+   * GtkAdjustment::value-changed:
+   * @adjustment: the object which received the signal.
+   *
+   * Emitted when the #GtkAdjustment value field has been changed.
+   */
   adjustment_signals[VALUE_CHANGED] =
     g_signal_new (I_("value-changed"),
                  G_OBJECT_CLASS_TYPE (class),
@@ -318,6 +352,19 @@ gtk_adjustment_dispatch_properties_changed (GObject     *object,
     }
 }
 
+/**
+ * gtk_adjustment_new:
+ * @value: the initial value.
+ * @lower: the minimum value.
+ * @upper: the maximum value.
+ * @step_increment: the step increment.
+ * @page_increment: the page increment.
+ * @page_size: the page size.
+ *
+ * Creates a new #GtkAdjustment.
+ *
+ * Returns: a new #GtkAdjustment.
+ */
 GtkAdjustment *
 gtk_adjustment_new (gdouble value,
                    gdouble lower,
@@ -353,6 +400,18 @@ gtk_adjustment_get_value (GtkAdjustment *adjustment)
   return adjustment->value;
 }
 
+/**
+ * gtk_adjustment_set_value:
+ * @adjustment: a #GtkAdjustment.
+ * @value: the new value.
+ *
+ * Sets the #GtkAdjustment value. The value is clamped to lie between
+ * #GtkAdjustment.lower and #GtkAdjustment.upper.
+ *
+ * Note that for adjustments which are used in a #GtkScrollbar, the effective
+ * range of allowed values goes from #GtkAdjustment.lower to
+ * #GtkAdjustment.upper - #GtkAdjustment.page_size.
+ */
 void
 gtk_adjustment_set_value (GtkAdjustment *adjustment,
                          gdouble        value)
@@ -656,6 +715,14 @@ gtk_adjustment_configure (GtkAdjustment *adjustment,
     gtk_adjustment_value_changed (adjustment);
 }
 
+/**
+ * gtk_adjustment_changed:
+ * @adjustment: a #GtkAdjustment
+ *
+ * Emits a #GtkAdjustment::changed signal from the #GtkAdjustment.
+ * This is typically called by the owner of the #GtkAdjustment after it has
+ * changed any of the #GtkAdjustment fields other than the value.
+ */
 void
 gtk_adjustment_changed (GtkAdjustment *adjustment)
 {
@@ -664,6 +731,14 @@ gtk_adjustment_changed (GtkAdjustment *adjustment)
   g_signal_emit (adjustment, adjustment_signals[CHANGED], 0);
 }
 
+/**
+ * gtk_adjustment_value_changed:
+ * @adjustment: a #GtkAdjustment
+ *
+ * Emits a #GtkAdjustment::value_changed signal from the #GtkAdjustment.
+ * This is typically called by the owner of the #GtkAdjustment after it has
+ * changed the #GtkAdjustment value field.
+ */
 void
 gtk_adjustment_value_changed (GtkAdjustment *adjustment)
 {
@@ -673,6 +748,19 @@ gtk_adjustment_value_changed (GtkAdjustment *adjustment)
   g_object_notify (G_OBJECT (adjustment), "value");
 }
 
+/**
+ * gtk_adjustment_clamp_page:
+ * @adjustment: a #GtkAdjustment.
+ * @lower: the lower value.
+ * @upper: the upper value.
+ *
+ * Updates the #GtkAdjustment #GtkAdjustment.value to ensure that the range
+ * between @lower and @upper is in the current page (i.e. between
+ * #GtkAdjustment.value and #GtkAdjustment.value + #GtkAdjustment.page_size).
+ * If the range is larger than the page size, then only the start of it will
+ * be in the current page.
+ * A #GtkAdjustment::changed signal will be emitted if the value is changed.
+ */
 void
 gtk_adjustment_clamp_page (GtkAdjustment *adjustment,
                           gdouble        lower,

diff --git a/gtk/gtkadjustment.h b/gtk/gtkadjustment.h
index 7cac64292cbed2c3ff797e12ca692ac87cf3ae1c..319953b342dbf1a823b33771cf1c1c71ea8f5d4d 100644 (file)
--- a/gtk/gtkadjustment.h
+++ b/gtk/gtkadjustment.h
@@ -46,6 +46,22 @@ G_BEGIN_DECLS
 typedef struct _GtkAdjustment      GtkAdjustment;
 typedef struct _GtkAdjustmentClass  GtkAdjustmentClass;
 
+/**
+ * GtkAdjustment:
+ * @lower: the minimum value.
+ * @upper: the maximum value.
+ * @value: the current value.
+ * @step_increment: the increment to use to make minor changes to the @value.
+ *   In a #GtkScrollbar this increment is used when the mouse is clicked on the
+ *   arrows at the top and bottom of the scrollbar, to scroll by a small amount.
+ * @page_increment: the increment to use to make major changes to the @value.
+ *   In a #GtkScrollbar this increment is used when the mouse is clicked in the
+ *   trough, to scroll by a large amount.
+ * @page_size: In a #GtkScrollbar this is the size of the area which is currently
+ *   visible.
+ *
+ * The #GtkAdjustment struct contains the following fields.
+ */
 struct _GtkAdjustment
 {
   GInitiallyUnowned parent_instance;