GNOME.org
 

[gtk/ebassi/gidocgen: 252/500] adjustment: Convert docs


commit 085b0b7c08c07aa3142e15cd1cfe53e95063c66e
Author: Matthias Clasen <mclasen redhat com>
Date:   Sat Feb 27 10:51:45 2021 -0500

    adjustment:  Convert docs

 gtk/gtkadjustment.c | 197 +++++++++++++++++++++++++++-------------------------
 gtk/gtkadjustment.h |   6 --
 2 files changed, 103 insertions(+), 100 deletions(-)
---
diff --git a/gtk/gtkadjustment.c b/gtk/gtkadjustment.c
index 67713a7db0..168fbe71c9 100644
--- a/gtk/gtkadjustment.c
+++ b/gtk/gtkadjustment.c
@@ -31,17 +31,17 @@
 
 
 /**
- * SECTION:gtkadjustment
- * @Short_description: A representation of an adjustable bounded value
- * @Title: GtkAdjustment
+ * 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 #GtkScrollbar and #GtkScale).
+ * The `GtkAdjustment` object represents a value which has an associated lower
+ * and upper bound.
  *
- * The #GtkAdjustment object does not update the value itself. Instead
- * it is left up to the owner of the #GtkAdjustment to control the value.
+ * It also contains step and page increments, and a page size. It is used
+ * within several GTK widgets, including [class@Gtk.SpinButton],
+ * [class@Gtk.Viewport], [class@Gtk.Scrollbar] and [class@Gtk.Scale].
+ *
+ * The `GtkAdjustment` object does not update the value itself. Instead
+ * it is left up to the owner of the `GtkAdjustment` to control the value.
  */
 
 
@@ -130,7 +130,7 @@ gtk_adjustment_class_init (GtkAdjustmentClass *class)
   class->value_changed = NULL;
 
   /**
-   * GtkAdjustment:value:
+   * GtkAdjustment:value: (attributes org.gtk.Property.get=gtk_adjustment_get_value 
org.gtk.Property.set=gtk_adjustment_set_value)
    *
    * The value of the adjustment.
    */
@@ -143,7 +143,7 @@ gtk_adjustment_class_init (GtkAdjustmentClass *class)
                            GTK_PARAM_READWRITE);
 
   /**
-   * GtkAdjustment:lower:
+   * GtkAdjustment:lower: (attributes org.gtk.Property.get=gtk_adjustment_get_lower 
org.gtk.Property.set=gtk_adjustment_set_lower)
    *
    * The minimum value of the adjustment.
    */
@@ -156,11 +156,11 @@ gtk_adjustment_class_init (GtkAdjustmentClass *class)
                            GTK_PARAM_READWRITE);
 
   /**
-   * GtkAdjustment:upper:
+   * GtkAdjustment:upper: (attributes org.gtk.Property.get=gtk_adjustment_get_upper 
org.gtk.Property.set=gtk_adjustment_set_upper)
    *
    * The maximum value of the adjustment.
-   * Note that values will be restricted by
-   * `upper - page-size` if the page-size
+   *
+   * Note that values will be restricted by `upper - page-size` if the page-size
    * property is nonzero.
    */
   adjustment_props[PROP_UPPER] =
@@ -172,7 +172,7 @@ gtk_adjustment_class_init (GtkAdjustmentClass *class)
                            GTK_PARAM_READWRITE);
 
   /**
-   * GtkAdjustment:step-increment:
+   * GtkAdjustment:step-increment: (attributes org.gtk.Property.get=gtk_adjustment_get_step_increment 
org.gtk.Property.set=gtk_adjustment_set_step_increment)
    *
    * The step increment of the adjustment.
    */
@@ -185,7 +185,7 @@ gtk_adjustment_class_init (GtkAdjustmentClass *class)
                            GTK_PARAM_READWRITE);
 
   /**
-   * GtkAdjustment:page-increment:
+   * GtkAdjustment:page-increment: (attributes org.gtk.Property.get=gtk_adjustment_get_page_increment 
org.gtk.Property.set=gtk_adjustment_set_page_increment)
    *
    * The page increment of the adjustment.
    */
@@ -198,12 +198,13 @@ gtk_adjustment_class_init (GtkAdjustmentClass *class)
                            GTK_PARAM_READWRITE);
 
   /**
-   * GtkAdjustment:page-size:
+   * GtkAdjustment:page-size: (attributes org.gtk.Property.get=gtk_adjustment_get_page_size 
org.gtk.Property.set=gtk_adjustment_set_page_size)
    *
    * The page size of the adjustment.
+   *
    * Note that the page-size is irrelevant and should be set to zero
    * if the adjustment is used for a simple scalar value, e.g. in a
-   * #GtkSpinButton.
+   * `GtkSpinButton`.
    */
   adjustment_props[PROP_PAGE_SIZE] =
       g_param_spec_double ("page-size",
@@ -219,8 +220,11 @@ gtk_adjustment_class_init (GtkAdjustmentClass *class)
    * GtkAdjustment::changed:
    * @adjustment: the object which received the signal
    *
-   * Emitted when one or more of the #GtkAdjustment properties have been
-   * changed, other than the #GtkAdjustment:value property.
+   * Emitted when one or more of the `GtkAdjustment` properties have been
+   * changed.
+   *
+   * Note that the [property@Gtk.Adjustment:value] property is
+   * covered by the [signal@Gtk.Adjustment::value-changed] signal.
    */
   adjustment_signals[CHANGED] =
     g_signal_new (I_("changed"),
@@ -235,7 +239,7 @@ gtk_adjustment_class_init (GtkAdjustmentClass *class)
    * GtkAdjustment::value-changed:
    * @adjustment: the object which received the signal
    *
-   * Emitted when the #GtkAdjustment:value property has been changed.
+   * Emitted when the value has been changed.
    */
   adjustment_signals[VALUE_CHANGED] =
     g_signal_new (I_("value-changed"),
@@ -368,9 +372,9 @@ gtk_adjustment_dispatch_properties_changed (GObject     *object,
  * @page_increment: the page increment
  * @page_size: the page size
  *
- * Creates a new #GtkAdjustment.
+ * Creates a new `GtkAdjustment`.
  *
- * Returns: a new #GtkAdjustment
+ * Returns: a new `GtkAdjustment`
  */
 GtkAdjustment *
 gtk_adjustment_new (double value,
@@ -391,14 +395,13 @@ gtk_adjustment_new (double value,
 }
 
 /**
- * gtk_adjustment_get_value:
- * @adjustment: a #GtkAdjustment
+ * gtk_adjustment_get_value: (attributes org.gtk.Method.get_property=value)
+ * @adjustment: a `GtkAdjustment`
  *
  * Gets the current value of the adjustment.
- * See gtk_adjustment_set_value().
  *
  * Returns: The current value of the adjustment
- **/
+ */
 double
 gtk_adjustment_get_value (GtkAdjustment *adjustment)
 {
@@ -530,16 +533,19 @@ gtk_adjustment_set_value_internal (GtkAdjustment *adjustment,
 }
 
 /**
- * gtk_adjustment_set_value:
- * @adjustment: a #GtkAdjustment
+ * gtk_adjustment_set_value: (attributes org.gtk.Method.set_property=value)
+ * @adjustment: a `GtkAdjustment`
  * @value: the new value
  *
- * Sets the #GtkAdjustment value. The value is clamped to lie between
- * #GtkAdjustment:lower and #GtkAdjustment:upper.
+ * Sets the `GtkAdjustment` value.
  *
- * 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.
+ * The value is clamped to lie between [property@Gtk.Adjustment:lower]
+ * and [property@Gtk.Adjustment:upper].
+ *
+ * Note that for adjustments which are used in a `GtkScrollbar`,
+ * the effective range of allowed values goes from
+ * [property@Gtk.Adjustment:lower] to
+ * [property@Gtk.Adjustment:upper] - [property@Gtk.Adjustment:page-size].
  */
 void
 gtk_adjustment_set_value (GtkAdjustment *adjustment,
@@ -560,8 +566,8 @@ gtk_adjustment_animate_to_value (GtkAdjustment *adjustment,
 }
 
 /**
- * gtk_adjustment_get_lower:
- * @adjustment: a #GtkAdjustment
+ * gtk_adjustment_get_lower: (attributes org.gtk.Method.get_property=lower)
+ * @adjustment: a `GtkAdjustment`
  *
  * Retrieves the minimum value of the adjustment.
  *
@@ -578,24 +584,24 @@ gtk_adjustment_get_lower (GtkAdjustment *adjustment)
 }
 
 /**
- * gtk_adjustment_set_lower:
- * @adjustment: a #GtkAdjustment
+ * gtk_adjustment_set_lower: (attributes org.gtk.Method.set_property=lower)
+ * @adjustment: a `GtkAdjustment`
  * @lower: the new minimum value
  *
  * Sets the minimum value of the adjustment.
  *
  * When setting multiple adjustment properties via their individual
- * setters, multiple #GtkAdjustment::changed signals will be emitted.
- * However, since the emission of the #GtkAdjustment::changed signal
- * is tied to the emission of the #GObject::notify signals of the changed
- * properties, it’s possible to compress the #GtkAdjustment::changed
- * signals into one by calling g_object_freeze_notify() and
- * g_object_thaw_notify() around the calls to the individual setters.
+ * setters, multiple [signal@Gtk.Adjustment::changed] signals will
+ * be emitted. However, since the emission of the
+ * [signal@Gtk.Adjustment::changed] signal is tied to the emission
+ * of the ::notify signals of the changed properties, it’s possible
+ * to compress the [signal@Gtk.Adjustment::changed] signals into one
+ * by calling g_object_freeze_notify() and g_object_thaw_notify()
+ * around the calls to the individual setters.
  *
  * Alternatively, using a single g_object_set() for all the properties
- * to change, or using gtk_adjustment_configure() has the same effect
- * of compressing #GtkAdjustment::changed emissions.
- **/
+ * to change, or using [method@Gtk.Adjustment.configure] has the same effect.
+ */
 void
 gtk_adjustment_set_lower (GtkAdjustment *adjustment,
                           double         lower)
@@ -612,13 +618,13 @@ gtk_adjustment_set_lower (GtkAdjustment *adjustment,
 }
 
 /**
- * gtk_adjustment_get_upper:
- * @adjustment: a #GtkAdjustment
+ * gtk_adjustment_get_upper: (attributes org.gtk.Method.get_property=upper)
+ * @adjustment: a `GtkAdjustment`
  *
  * Retrieves the maximum value of the adjustment.
  *
  * Returns: The current maximum value of the adjustment
- **/
+ */
 double
 gtk_adjustment_get_upper (GtkAdjustment *adjustment)
 {
@@ -630,8 +636,8 @@ gtk_adjustment_get_upper (GtkAdjustment *adjustment)
 }
 
 /**
- * gtk_adjustment_set_upper:
- * @adjustment: a #GtkAdjustment
+ * gtk_adjustment_set_upper: (attributes org.gtk.Method.set_property=upper)
+ * @adjustment: a `GtkAdjustment`
  * @upper: the new maximum value
  *
  * Sets the maximum value of the adjustment.
@@ -639,10 +645,10 @@ gtk_adjustment_get_upper (GtkAdjustment *adjustment)
  * Note that values will be restricted by `upper - page-size`
  * if the page-size property is nonzero.
  *
- * See gtk_adjustment_set_lower() about how to compress multiple
- * emissions of the #GtkAdjustment::changed signal when setting
- * multiple adjustment properties.
- **/
+ * See [method@Gtk.Adjustment.set_lower] about how to compress
+ * multiple emissions of the [signal@Gtk.Adjustment::changed]
+ * signal when setting multiple adjustment properties.
+ */
 void
 gtk_adjustment_set_upper (GtkAdjustment *adjustment,
                           double         upper)
@@ -659,13 +665,13 @@ gtk_adjustment_set_upper (GtkAdjustment *adjustment,
 }
 
 /**
- * gtk_adjustment_get_step_increment:
- * @adjustment: a #GtkAdjustment
+ * gtk_adjustment_get_step_increment: (attributes org.gtk.Method.get_property=step-increment)
+ * @adjustment: a `GtkAdjustment`
  *
  * Retrieves the step increment of the adjustment.
  *
  * Returns: The current step increment of the adjustment.
- **/
+ */
 double
 gtk_adjustment_get_step_increment (GtkAdjustment *adjustment)
 {
@@ -677,16 +683,16 @@ gtk_adjustment_get_step_increment (GtkAdjustment *adjustment)
 }
 
 /**
- * gtk_adjustment_set_step_increment:
- * @adjustment: a #GtkAdjustment
+ * gtk_adjustment_set_step_increment: (attributes org.gtk.Method.set_property=step-increment)
+ * @adjustment: a `GtkAdjustment`
  * @step_increment: the new step increment
  *
  * Sets the step increment of the adjustment.
  *
- * See gtk_adjustment_set_lower() about how to compress multiple
- * emissions of the #GtkAdjustment::changed signal when setting
- * multiple adjustment properties.
- **/
+ * See [method@Gtk.Adjustment.set_lower] about how to compress
+ * multiple emissions of the [signal@Gtk.Adjustment::changed]
+ * signal when setting multiple adjustment properties.
+ */
 void
 gtk_adjustment_set_step_increment (GtkAdjustment *adjustment,
                                    double         step_increment)
@@ -703,8 +709,8 @@ gtk_adjustment_set_step_increment (GtkAdjustment *adjustment,
 }
 
 /**
- * gtk_adjustment_get_page_increment:
- * @adjustment: a #GtkAdjustment
+ * gtk_adjustment_get_page_increment: (attributes org.gtk.Method.get_property=page-increment)
+ * @adjustment: a `GtkAdjustment`
  *
  * Retrieves the page increment of the adjustment.
  *
@@ -721,16 +727,16 @@ gtk_adjustment_get_page_increment (GtkAdjustment *adjustment)
 }
 
 /**
- * gtk_adjustment_set_page_increment:
- * @adjustment: a #GtkAdjustment
+ * gtk_adjustment_set_page_increment: (attributes org.gtk.Method.set_property=page-increment)
+ * @adjustment: a `GtkAdjustment`
  * @page_increment: the new page increment
  *
  * Sets the page increment of the adjustment.
  *
- * See gtk_adjustment_set_lower() about how to compress multiple
- * emissions of the #GtkAdjustment::changed signal when setting
- * multiple adjustment properties.
- **/
+ * See [method@Gtk.Adjustment.set_lower] about how to compress
+ * multiple emissions of the [signal@Gtk.Adjustment::changed]
+ * signal when setting multiple adjustment properties.
+ */
 void
 gtk_adjustment_set_page_increment (GtkAdjustment *adjustment,
                                    double         page_increment)
@@ -747,8 +753,8 @@ gtk_adjustment_set_page_increment (GtkAdjustment *adjustment,
 }
 
 /**
- * gtk_adjustment_get_page_size:
- * @adjustment: a #GtkAdjustment
+ * gtk_adjustment_get_page_size: (attributes org.gtk.Method.get_property=page-size)
+ * @adjustment: a `GtkAdjustment`
  *
  * Retrieves the page size of the adjustment.
  *
@@ -765,16 +771,16 @@ gtk_adjustment_get_page_size (GtkAdjustment *adjustment)
 }
 
 /**
- * gtk_adjustment_set_page_size:
- * @adjustment: a #GtkAdjustment
+ * gtk_adjustment_set_page_size: (attributes org.gtk.Method.set_property=page-size)
+ * @adjustment: a `GtkAdjustment`
  * @page_size: the new page size
  *
  * Sets the page size of the adjustment.
  *
- * See gtk_adjustment_set_lower() about how to compress multiple
- * emissions of the GtkAdjustment::changed signal when setting
- * multiple adjustment properties.
- **/
+ * See [method@Gtk.Adjustment.set_lower] about how to compress
+ * multiple emissions of the [signal@Gtk.Adjustment::changed]
+ * signal when setting multiple adjustment properties.
+ */
 void
 gtk_adjustment_set_page_size (GtkAdjustment *adjustment,
                               double         page_size)
@@ -792,7 +798,7 @@ gtk_adjustment_set_page_size (GtkAdjustment *adjustment,
 
 /**
  * gtk_adjustment_configure:
- * @adjustment: a #GtkAdjustment
+ * @adjustment: a `GtkAdjustment`
  * @value: the new value
  * @lower: the new minimum value
  * @upper: the new maximum value
@@ -803,10 +809,11 @@ gtk_adjustment_set_page_size (GtkAdjustment *adjustment,
  * Sets all properties of the adjustment at once.
  *
  * Use this function to avoid multiple emissions of the
- * #GtkAdjustment::changed signal. See gtk_adjustment_set_lower()
- * for an alternative way of compressing multiple emissions of
- * #GtkAdjustment::changed into one.
- **/
+ * [signal@Gtk.Adjustment::changed] signal. See
+ * [method@Gtk.Adjustment.set_lower] for an alternative
+ * way of compressing multiple emissions of
+ * [signal@Gtk.Adjustment::changed] into one.
+ */
 void
 gtk_adjustment_configure (GtkAdjustment *adjustment,
                           double         value,
@@ -853,17 +860,19 @@ gtk_adjustment_configure (GtkAdjustment *adjustment,
 
 /**
  * gtk_adjustment_clamp_page:
- * @adjustment: a #GtkAdjustment
+ * @adjustment: a `GtkAdjustment`
  * @lower: the lower value
  * @upper: the upper value
  *
- * Updates the #GtkAdjustment:value property 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.
+ * Updates the value property to ensure that the range
+ * between @lower and @upper is in the current page.
+ *
+ * The current page goes from `value` to `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 #GtkAdjustment::value-changed signal will be emitted if the value is changed.
+ * A [signal@Gtk.Adjustment::value-changed] signal will be emitted
+ * if the value is changed.
  */
 void
 gtk_adjustment_clamp_page (GtkAdjustment *adjustment,
@@ -897,7 +906,7 @@ gtk_adjustment_clamp_page (GtkAdjustment *adjustment,
 
 /**
  * gtk_adjustment_get_minimum_increment:
- * @adjustment: a #GtkAdjustment
+ * @adjustment: a `GtkAdjustment`
  *
  * Gets the smaller of step increment and page increment.
  *
diff --git a/gtk/gtkadjustment.h b/gtk/gtkadjustment.h
index 997c2b4df4..7f5ce89a34 100644
--- a/gtk/gtkadjustment.h
+++ b/gtk/gtkadjustment.h
@@ -44,12 +44,6 @@ G_BEGIN_DECLS
 
 typedef struct _GtkAdjustmentClass    GtkAdjustmentClass;
 
-/**
- * GtkAdjustment:
- *
- * The #GtkAdjustment-struct contains only private fields and
- * should not be directly accessed.
- */
 struct _GtkAdjustment
 {
   GInitiallyUnowned parent_instance;
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]