GtkScrollable: Improve the documentation text.

1 files changed, 27 insertions, 27 deletions

diff --git a/gtk/gtkscrollable.c b/gtk/gtkscrollable.c
index ca0d8a4ea4..eb6e046f50 100644
--- a/gtk/gtkscrollable.c
+++ b/gtk/gtkscrollable.c
@@ -22,37 +22,37 @@
  * @Short_Description: An interface for scrollable widgets
  * @Title: GtkScrollable
  *
- * #GtkScrollable is interface that is implemented by widgets with native
+ * #GtkScrollable is an interface that is implemented by widgets with native
  * scrolling ability.
  *
- * To implement this interface, all one needs to do is to override
+ * To implement this interface you should override the
  * #GtkScrollable:hadjustment and #GtkScrollable:vadjustment properties.
  *
  * <refsect2>
  * <title>Creating a scrollable widget</title>
  * <para>
- * There are some common things all scrollable widgets will need to do.
+ * All scrollable widgets should do the following.
  *
  * <orderedlist>
  *   <listitem>
  *     <para>
- *       When parent sets adjustments, widget needs to populate adjustment's
+ *       When a parent widget sets the scrollable child widget's adjustments, the widget should populate the adjustments'
  *       #GtkAdjustment:lower, #GtkAdjustment:upper,
  *       #GtkAdjustment:step-increment, #GtkAdjustment:page-increment and
- *       #GtkAdjustment:page-size properties and connect to
+ *       #GtkAdjustment:page-size properties and connect to the
  *       #GtkAdjustment::value-changed signal.
  *     </para>
  *   </listitem>
  *   <listitem>
  *     <para>
- *       When parent allocates space to child, scrollable widget needs to update
- *       properties listed under 1 with new values.
+ *       When the parent allocates space to the scrollable child widget, the widget should update
+ *       the adjustments' properties with new values.
  *     </para>
  *   </listitem>
  *   <listitem>
  *     <para>
- *       When any of the adjustments emits #GtkAdjustment::value-changed signal,
- *       scrollable widget needs to scroll it's contents.
+ *       When any of the adjustments emits the #GtkAdjustment::value-changed signal,
+ *       the scrollable widget should scroll its contents.
  *     </para>
  *   </listitem>
  * </orderedlist>
@@ -77,15 +77,15 @@ gtk_scrollable_default_init (GtkScrollableInterface *iface)
   /**
    * GtkScrollable:hadjustment:
    *
-   * Horizontal #GtkAdjustment of scrollable widget. This adjustment is
-   * shared between scrollable widget and it's parent.
+   * Horizontal #GtkAdjustment of the scrollable widget. This adjustment is
+   * shared between the scrollable widget and its parent.
    *
    * Since: 3.0
    */
   pspec = g_param_spec_object ("hadjustment",
                                P_("Horizontal adjustment"),
                                P_("Horizontal adjustment that is shared "
-                                  "between scrollable widget and it's "
+                                  "between the scrollable widget and its "
                                   "controller"),
                                GTK_TYPE_ADJUSTMENT,
                                GTK_PARAM_READWRITE | G_PARAM_CONSTRUCT);
@@ -94,15 +94,15 @@ gtk_scrollable_default_init (GtkScrollableInterface *iface)
   /**
    * GtkScrollable:vadjustment:
    *
-   * Verical #GtkAdjustment of scrollable widget. This adjustment is shared
-   * between scrollable widget and it's parent.
+   * Verical #GtkAdjustment of the scrollable widget. This adjustment is shared
+   * between the scrollable widget and its parent.
    *
    * Since: 3.0
    */
   pspec = g_param_spec_object ("vadjustment",
                                P_("Vertical adjustment"),
                                P_("Vertical adjustment that is shared "
-                                  "between scrollable widget and it's "
+                                  "between the scrollable widget and its "
                                   "controller"),
                                GTK_TYPE_ADJUSTMENT,
                                GTK_PARAM_READWRITE | G_PARAM_CONSTRUCT);
@@ -111,8 +111,8 @@ gtk_scrollable_default_init (GtkScrollableInterface *iface)
   /**
    * GtkScrollable:hscroll-policy:
    *
-   * Determines whether horizontal scrolling should commence once the scrollable 
-   * widget is allocated less than it's minimum width or less than it's natural width.
+   * Determines whether horizontal scrolling should start once the scrollable
+   * widget is allocated less than its minimum width or less than its natural width.
    *
    * Since: 3.0
    */
@@ -127,8 +127,8 @@ gtk_scrollable_default_init (GtkScrollableInterface *iface)
   /**
    * GtkScrollable:vscroll-policy:
    *
-   * Determines whether vertical scrolling should commence once the scrollable 
-   * widget is allocated less than it's minimum height or less than it's natural height.
+   * Determines whether vertical scrolling should start once the scrollable
+   * widget is allocated less than its minimum height or less than its natural height.
    *
    * Since: 3.0
    */
@@ -145,7 +145,7 @@ gtk_scrollable_default_init (GtkScrollableInterface *iface)
  * gtk_scrollable_get_hadjustment:
  * @scrollable: a #GtkScrollable
  *
- * Retrieves the #GtkAdjustment, used for horizontal scrolling.
+ * Retrieves the #GtkAdjustment used for horizontal scrolling.
  *
  * Return value: (transfer none): horizontal #GtkAdjustment.
  *
@@ -193,7 +193,7 @@ gtk_scrollable_set_hadjustment (GtkScrollable *scrollable,
  * gtk_scrollable_get_vadjustment:
  * @scrollable: a #GtkScrollable
  *
- * Retrieves the #GtkAdjustment, used for vertical scrolling.
+ * Retrieves the #GtkAdjustment used for vertical scrolling.
  *
  * Return value: (transfer none): vertical #GtkAdjustment.
  *
@@ -265,9 +265,9 @@ gtk_scrollable_get_hscroll_policy (GtkScrollable *scrollable)
  * @scrollable: a #GtkScrollable
  * @policy: the horizontal #GtkScrollablePolicy
  *
- * Sets the #GtkScrollablePolicy to determine whether 
- * horizontal scrolling should commence below minimum or
- * below natural width.
+ * Sets the #GtkScrollablePolicy to determine whether
+ * horizontal scrolling should start below the minimum width or
+ * below the natural width.
  *
  * Since: 3.0
  **/
@@ -307,9 +307,9 @@ gtk_scrollable_get_vscroll_policy (GtkScrollable *scrollable)
  * @scrollable: a #GtkScrollable
  * @policy: the vertical #GtkScrollablePolicy
  *
- * Sets the #GtkScrollablePolicy to determine whether 
- * vertical scrolling should commence below minimum or
- * below natural height.
+ * Sets the #GtkScrollablePolicy to determine whether
+ * vertical scrolling should start below the minimum height or
+ * below the natural height.
  *
  * Since: 3.0
  **/