[gtk/ebassi/gidocgen: 33/478] docs: Clean up the first paragraph for various symbols

[Emmanuele Bassi <ebassi src gnome org>]

commit 8dd280c5f6e51c8681a2c8e2ad11ce6d12faf672
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Thu Feb 18 18:17:56 2021 +0000

    docs: Clean up the first paragraph for various symbols
    
    The documentation engine will use the first paragraph as the summary for
    a type or constant.

 gtk/gtkaccelgroup.c      | 17 ++++++++++-------
 gtk/gtkaccessible.c      |  4 +++-
 gtk/gtkbuilder.c         |  5 +++--
 gtk/gtkbuilderscope.h    |  7 ++++---
 gtk/gtkbutton.c          |  3 +--
 gtk/gtkcombobox.c        | 12 +++++-------
 gtk/gtkconstraint.c      |  5 +++--
 gtk/gtkdragsource.c      |  6 ++++--
 gtk/gtkentrycompletion.h |  1 +
 gtk/gtkeventcontroller.c |  5 +++--
 gtk/gtkheaderbar.c       |  3 +++
 gtk/gtkicontheme.c       |  9 +++++----
 gtk/gtkimage.h           | 15 ++++++++-------
 gtk/gtklockbutton.c      | 10 ++++++----
 gtk/gtkmountoperation.c  |  6 +++++-
 gtk/gtkpicture.c         | 28 +++++++++++++++-------------
 gtk/gtktextbuffer.c      | 10 ++++++----
 gtk/gtktextiter.c        |  2 ++
 gtk/gtktextmark.c        |  2 ++
 gtk/gtktexttag.c         |  2 ++
 gtk/gtktexttagtable.c    |  2 ++
 gtk/gtktextview.c        |  6 ++++--
 gtk/gtktooltip.c         |  2 ++
 gtk/gtktreeselection.h   |  8 +++++---
 gtk/gtktreesortable.h    | 14 +++++++-------
 gtk/gtktreeviewcolumn.h  | 12 +++++++-----
 gtk/gtkwidget.h          |  6 +-----
 27 files changed, 119 insertions(+), 83 deletions(-)
---
diff --git a/gtk/gtkaccelgroup.c b/gtk/gtkaccelgroup.c
index 376b4ae7d0..ff33289065 100644
--- a/gtk/gtkaccelgroup.c
+++ b/gtk/gtkaccelgroup.c
@@ -53,10 +53,11 @@
  * @modifiers: modifier mask
  *
  * Determines whether a given keyval and modifier mask constitute
- * a valid keyboard accelerator. For example, the #GDK_KEY_a keyval
- * plus #GDK_CONTROL_MASK is valid - this is a “Ctrl+a” accelerator.
- * But, you can't, for instance, use the #GDK_KEY_Control_L keyval
- * as an accelerator.
+ * a valid keyboard accelerator.
+ *
+ * For example, the %GDK_KEY_a keyval plus %GDK_CONTROL_MASK mark is valid,
+ * and matches the “Ctrl+a” accelerator. But, you can't, for instance, use
+ * the %GDK_KEY_Control_L keyval as an accelerator.
  *
  * Returns: %TRUE if the accelerator is valid
  */
@@ -558,13 +559,15 @@ gtk_accelerator_name_with_keycode (GdkDisplay      *display,
  * @accelerator_mods: accelerator modifier mask
  *
  * Converts an accelerator keyval and modifier mask into a string
- * parseable by gtk_accelerator_parse(). For example, if you pass in
- * #GDK_KEY_q and #GDK_CONTROL_MASK, this function returns “<Control>q”.
+ * parseable by gtk_accelerator_parse().
+ *
+ * For example, if you pass in %GDK_KEY_q and %GDK_CONTROL_MASK,
+ * this function returns `<Control>q`.
  *
  * If you need to display accelerators in the user interface,
  * see gtk_accelerator_get_label().
  *
- * Returns: a newly-allocated accelerator name
+ * Returns: (transfer full): a newly-allocated accelerator name
  */
 char *
 gtk_accelerator_name (guint           accelerator_key,
diff --git a/gtk/gtkaccessible.c b/gtk/gtkaccessible.c
index c5934c80f8..475ac1114e 100644
--- a/gtk/gtkaccessible.c
+++ b/gtk/gtkaccessible.c
@@ -25,7 +25,9 @@
  *
  * GtkAccessible provides an interface for describing a UI element, like a
  * #GtkWidget, in a way that can be consumed by Assistive Technologies, or
- * “AT”. Every accessible implementation has:
+ * “AT”.
+ *
+ * Every accessible implementation has:
  *
  *  - a “role”, represented by a value of the #GtkAccessibleRole enumeration
  *  - an “attribute”, represented by a set of #GtkAccessibleState,
diff --git a/gtk/gtkbuilder.c b/gtk/gtkbuilder.c
index 29dbe8ef9d..4a65fb3b13 100644
--- a/gtk/gtkbuilder.c
+++ b/gtk/gtkbuilder.c
@@ -24,8 +24,9 @@
  * @Title: GtkBuilder
  *
  * A GtkBuilder is an auxiliary object that reads textual descriptions
- * of a user interface and instantiates the described objects. To create
- * a GtkBuilder from a user interface description, call
+ * of a user interface and instantiates the described objects.
+ *
+ * To create a GtkBuilder from a user interface description, call
  * gtk_builder_new_from_file(), gtk_builder_new_from_resource() or
  * gtk_builder_new_from_string().
  *
diff --git a/gtk/gtkbuilderscope.h b/gtk/gtkbuilderscope.h
index 7d0ae96320..4ca48e2611 100644
--- a/gtk/gtkbuilderscope.h
+++ b/gtk/gtkbuilderscope.h
@@ -39,10 +39,11 @@ G_DECLARE_INTERFACE (GtkBuilderScope, gtk_builder_scope, GTK, BUILDER_SCOPE, GOb
  *   g_cclosure_new_swap() for details.
  *
  * The list of flags that can be passed to gtk_builder_create_closure().
+ *
  * New values may be added in the future for new features, so external
- * implementations of GtkBuilderScopeInterface should test the flags for unknown
- * values and raise a %GTK_BUILDER_ERROR_INVALID_ATTRIBUTE error when they
- * encounter one.
+ * implementations of [interface@Gtk.BuilderScope] should test the flags
+ * for unknown values and raise a %GTK_BUILDER_ERROR_INVALID_ATTRIBUTE error
+ * when they encounter one.
  */
 typedef enum { /*< prefix=GTK_BUILDER_CLOSURE >*/
   GTK_BUILDER_CLOSURE_SWAPPED = (1 << 0)
diff --git a/gtk/gtkbutton.c b/gtk/gtkbutton.c
index 7424895a17..8fbc1b45cd 100644
--- a/gtk/gtkbutton.c
+++ b/gtk/gtkbutton.c
@@ -28,8 +28,7 @@
  * @Title: GtkButton
  *
  * The #GtkButton widget is generally used to trigger a callback function that is
- * called when the button is pressed.  The various signals and how to use them
- * are outlined below.
+ * called when the button is pressed.
  *
  * The #GtkButton widget can hold any valid child widget.  That is, it can hold
  * almost any other standard #GtkWidget.  The most commonly used child is the
diff --git a/gtk/gtkcombobox.c b/gtk/gtkcombobox.c
index 0b2801e633..61a08cdbd2 100644
--- a/gtk/gtkcombobox.c
+++ b/gtk/gtkcombobox.c
@@ -49,12 +49,10 @@
  * @Title: GtkComboBox
  * @See_also: #GtkComboBoxText, #GtkTreeModel, #GtkCellRenderer
  *
- * A GtkComboBox is a widget that allows the user to choose from a list of
- * valid choices. The GtkComboBox displays the selected choice. When
- * activated, the GtkComboBox displays a popup which allows the user to
- * make a new choice. The style in which the selected value is displayed,
- * and the style of the popup is determined by the current theme. It may
- * be similar to a Windows-style combo box.
+ * A `GtkComboBox` is a widget that allows the user to choose from a list of
+ * valid choices. The `GtkComboBox` displays the selected choice; when
+ * activated, the `GtkComboBox` displays a popup which allows the user to
+ * make a new choice.
  *
  * The GtkComboBox uses the model-view pattern; the list of valid choices
  * is specified in the form of a tree model, and the display of the choices
@@ -73,7 +71,7 @@
  * simple alternative. Both GtkComboBox and #GtkComboBoxText can contain
  * an entry.
  *
- * # CSS nodes
+ * ## CSS nodes
  *
  * |[<!-- language="plain" -->
  * combobox
diff --git a/gtk/gtkconstraint.c b/gtk/gtkconstraint.c
index d3806b9737..90008d3dfe 100644
--- a/gtk/gtkconstraint.c
+++ b/gtk/gtkconstraint.c
@@ -23,8 +23,9 @@
  * @Short_description: The description of a constraint
  *
  * `GtkConstraint` describes a constraint between an attribute on a widget
- * and another attribute on another widget, expressed as a linear equation
- * like:
+ * and another attribute on another widget, expressed as a linear equation.
+ *
+ * For instance:
  *
  * ```
  *   target.attr1 = source.attr2 × multiplier + constant
diff --git a/gtk/gtkdragsource.c b/gtk/gtkdragsource.c
index 47f0ba179d..b6673c0564 100644
--- a/gtk/gtkdragsource.c
+++ b/gtk/gtkdragsource.c
@@ -46,8 +46,10 @@
  * @Short_description: Event controller to initiate DND operations
  * @Title: GtkDragSource
  *
- * GtkDragSource is an auxiliary object that is used to initiate
- * Drag-And-Drop operations. It can be set up with the necessary
+ * GtkDragSource is an event controller that is used to initiate
+ * Drag-And-Drop operations.
+ *
+ * GtkDragSource can be set up with the necessary
  * ingredients for a DND operation ahead of time. This includes
  * the source for the data that is being transferred, in the form
  * of a #GdkContentProvider, the desired action, and the icon to
diff --git a/gtk/gtkentrycompletion.h b/gtk/gtkentrycompletion.h
index 476aa9834d..540afc0d1c 100644
--- a/gtk/gtkentrycompletion.h
+++ b/gtk/gtkentrycompletion.h
@@ -46,6 +46,7 @@ typedef struct _GtkEntryCompletion            GtkEntryCompletion;
  *
  * A function which decides whether the row indicated by @iter matches
  * a given @key, and should be displayed as a possible completion for @key.
+ *
  * Note that @key is normalized and case-folded (see g_utf8_normalize()
  * and g_utf8_casefold()). If this is not appropriate, match functions
  * have access to the unmodified key via
diff --git a/gtk/gtkeventcontroller.c b/gtk/gtkeventcontroller.c
index f58865d7cd..7d1c9ea1d7 100644
--- a/gtk/gtkeventcontroller.c
+++ b/gtk/gtkeventcontroller.c
@@ -25,8 +25,9 @@
  * @See_also: #GtkGesture
  *
  * #GtkEventController is a base, low-level implementation for event
- * controllers. Those react to a series of #GdkEvents, and possibly trigger
- * actions as a consequence of those.
+ * controllers: ancillary object associated to widgets, which react
+ * to a series of #GdkEvents, and possibly trigger actions as a
+ * consequence.
  */
 
 #include "config.h"
diff --git a/gtk/gtkheaderbar.c b/gtk/gtkheaderbar.c
index 786dfb754e..821e29f99f 100644
--- a/gtk/gtkheaderbar.c
+++ b/gtk/gtkheaderbar.c
@@ -43,6 +43,9 @@
  * @Title: GtkHeaderBar
  * @See_also: #GtkBox, #GtkActionBar
  *
+ * `GtkHeaderBar` is a widget for creating custom title bars for
+ * [class@Gtk.Window].
+ *
  * GtkHeaderBar is similar to a horizontal #GtkBox. It allows children to 
  * be placed at the start or the end. In addition, it allows the window
  * title to be displayed. The title will be centered with respect to the
diff --git a/gtk/gtkicontheme.c b/gtk/gtkicontheme.c
index a5bfdaf5a0..e1e233d768 100644
--- a/gtk/gtkicontheme.c
+++ b/gtk/gtkicontheme.c
@@ -69,10 +69,11 @@
  * @Title: GtkIconTheme
  *
  * #GtkIconTheme provides a facility for looking up icons by name
- * and size. The main reason for using a name rather than simply
- * providing a filename is to allow different icons to be used
- * depending on what “icon theme” is selected
- * by the user. The operation of icon themes on Linux and Unix
+ * and size.
+ *
+ * The main reason for using a name rather than simply providing a filename
+ * is to allow different icons to be used depending on what “icon theme” is
+ * selected by the user. The operation of icon themes on Linux and Unix
  * follows the [Icon Theme Specification](http://www.freedesktop.org/Standards/icon-theme-spec)
  * There is a fallback icon theme, named `hicolor`, where applications
  * should install their icons, but additional icon themes can be installed
diff --git a/gtk/gtkimage.h b/gtk/gtkimage.h
index 6700b3d525..c63b37a1c1 100644
--- a/gtk/gtkimage.h
+++ b/gtk/gtkimage.h
@@ -49,13 +49,14 @@ typedef struct _GtkImage              GtkImage;
  * @GTK_IMAGE_GICON: the widget contains a #GIcon
  * @GTK_IMAGE_PAINTABLE: the widget contains a #GdkPaintable
  *
- * Describes the image data representation used by a #GtkImage. If you
- * want to get the image from the widget, you can only get the
- * currently-stored representation. e.g.  if the
- * gtk_image_get_storage_type() returns #GTK_IMAGE_PAINTABLE, then you can
- * call gtk_image_get_paintable().  For empty images, you can request any
- * storage type (call any of the "get" functions), but they will all
- * return %NULL values.
+ * Describes the image data representation used by a [class@Gtk.Image].
+ *
+ * If you want to get the image from the widget, you can only get the
+ * currently-stored representation; for instance, if the gtk_image_get_storage_type()
+ * returns %GTK_IMAGE_PAINTABLE, then you can call gtk_image_get_paintable().
+ *
+ * For empty images, you can request any storage type (call any of the "get"
+ * functions), but they will all return %NULL values.
  */
 typedef enum
 {
diff --git a/gtk/gtklockbutton.c b/gtk/gtklockbutton.c
index b9754b2e17..afed0d93f0 100644
--- a/gtk/gtklockbutton.c
+++ b/gtk/gtklockbutton.c
@@ -34,10 +34,12 @@
  *
  * GtkLockButton is a widget that can be used in control panels or
  * preference dialogs to allow users to obtain and revoke authorizations
- * needed to operate the controls. The required authorization is represented
- * by a #GPermission object. Concrete implementations of #GPermission may use
- * PolicyKit or some other authorization framework. To obtain a PolicyKit-based
- * #GPermission, use polkit_permission_new().
+ * needed to operate the controls.
+ *
+ * The required authorization is represented by a #GPermission object.
+ * Concrete implementations of #GPermission may use PolicyKit or some
+ * other authorization framework. To obtain a PolicyKit-based
+ * #GPermission, use `polkit_permission_new()`.
  *
  * If the user is not currently allowed to perform the action, but can obtain
  * the permission, the widget looks like this:
diff --git a/gtk/gtkmountoperation.c b/gtk/gtkmountoperation.c
index f5380863bd..c7b36081f0 100644
--- a/gtk/gtkmountoperation.c
+++ b/gtk/gtkmountoperation.c
@@ -63,10 +63,14 @@
 #include <glib/gprintf.h>
 
 /**
- * SECTION:filesystem
+ * SECTION:gtkmountoperation
  * @short_description: Functions for working with GIO
  * @Title: Filesystem utilities
  *
+ * `GtkMountOperation` is an implementation of `GMountOperation` that
+ * can use a graphical user interface when requiring information from
+ * the user, like passwords or other information.
+ *
  * The functions and objects described here make working with GTK and
  * GIO more convenient.
  *
diff --git a/gtk/gtkpicture.c b/gtk/gtkpicture.c
index 0668cad14b..2317b93e55 100644
--- a/gtk/gtkpicture.c
+++ b/gtk/gtkpicture.c
@@ -36,14 +36,16 @@
  * @Title: GtkPicture
  * @SeeAlso: #GdkPaintable, #GtkImage
  *
- * The #GtkPicture widget displays a #GdkPaintable. Many convenience functions
- * are provided to make pictures simple to use. For example, if you want to load
- * an image from a file, and then display that, there’s a convenience function
- * to do this:
- * |[<!-- language="C" -->
- *   GtkWidget *widget;
- *   widget = gtk_picture_new_for_filename ("myfile.png");
- * ]|
+ * The `GtkPicture` widget displays a `GdkPaintable`.
+ *
+ * Many convenience functions are provided to make pictures simple to use.
+ * For example, if you want to load an image from a file, and then display
+ * it, there’s a convenience function to do this:
+ *
+ * ```c
+ *   GtkWidget *widget = gtk_picture_new_for_filename ("myfile.png");
+ * ```
+ *
  * If the file isn’t loaded successfully, the picture will contain a
  * “broken image” icon similar to that used in many web browsers.
  * If you want to handle errors in loading the file yourself,
@@ -59,7 +61,7 @@
  * GtkPicture displays an image at its natural size. See #GtkImage if you want
  * to display a fixed-size image, such as an icon.
  *
- * # Sizing the paintable
+ * ## Sizing the paintable
  *
  * You can influence how the paintable is displayed inside the #GtkPicture.
  * By turning off #GtkPicture:keep-aspect-ratio you can allow the paintable
@@ -71,13 +73,13 @@
  * sure the paintable doesn't fill all available space but is instead displayed
  * at its original size.
  *
- * # CSS nodes
+ * ## CSS nodes
  *
- * GtkPicture has a single CSS node with the name picture.
+ * `GtkPicture` has a single CSS node with the name `picture`.
  *
- * # Accessibility
+ * ## Accessibility
  *
- * GtkPicture uses the #GTK_ACCESSIBLE_ROLE_IMG role.
+ * `GtkPicture` uses the `GTK_ACCESSIBLE_ROLE_IMG` role.
  */
 
 enum
diff --git a/gtk/gtktextbuffer.c b/gtk/gtktextbuffer.c
index 3302d07261..a1924d0e47 100644
--- a/gtk/gtktextbuffer.c
+++ b/gtk/gtktextbuffer.c
@@ -46,10 +46,12 @@
  * @Title: GtkTextBuffer
  * @See_also: #GtkTextView, #GtkTextIter, #GtkTextMark
  *
- * You may wish to begin by reading the
- * [text widget conceptual overview][TextWidget]
- * which gives an overview of all the objects and data
- * types related to the text widget and how they work together.
+ * Stores text (with or without attributes) for display in a
+ * [class@Gtk.TextView] widget.
+ *
+ * You may wish to begin by reading the [text widget conceptual overview][TextWidget]
+ * which gives an overview of all the objects and data types related to the
+ * text widget and how they work together.
  */
 
 typedef struct _GtkTextLogAttrCache GtkTextLogAttrCache;
diff --git a/gtk/gtktextiter.c b/gtk/gtktextiter.c
index 232634f18d..82d3e88b45 100644
--- a/gtk/gtktextiter.c
+++ b/gtk/gtktextiter.c
@@ -38,6 +38,8 @@
  * @Short_description: Text buffer iterator
  * @Title: GtkTextIter
  *
+ * An iterator for the contents of a [class@Gtk.TextBuffer]
+ *
  * You may wish to begin by reading the
  * [text widget conceptual overview][TextWidget]
  * which gives an overview of all the objects and data
diff --git a/gtk/gtktextmark.c b/gtk/gtktextmark.c
index ebfa6242bc..dfe79b5bd2 100644
--- a/gtk/gtktextmark.c
+++ b/gtk/gtktextmark.c
@@ -58,6 +58,8 @@
  * @Short_description: A position in the buffer preserved across buffer modifications
  * @Title: GtkTextMark
  *
+ * A position in a [class@Gtk.TextBuffer] preserved across modifications.
+ *
  * You may wish to begin by reading the
  * [text widget conceptual overview][TextWidget]
  * which gives an overview of all the objects and data
diff --git a/gtk/gtktexttag.c b/gtk/gtktexttag.c
index 727ed359da..fd10b2d06c 100644
--- a/gtk/gtktexttag.c
+++ b/gtk/gtktexttag.c
@@ -52,6 +52,8 @@
  * @Title: GtkTextTag
  * @Short_description: A tag that can be applied to text in a GtkTextBuffer
  *
+ * A tag that can be applied to text contained in a [class@Gtk.TextBuffer].
+ *
  * You may wish to begin by reading the
  * [text widget conceptual overview][TextWidget]
  * which gives an overview of all the objects and
diff --git a/gtk/gtktexttagtable.c b/gtk/gtktexttagtable.c
index 1435e7375c..db60c037d1 100644
--- a/gtk/gtktexttagtable.c
+++ b/gtk/gtktexttagtable.c
@@ -41,6 +41,8 @@
  * @Short_description: Collection of tags that can be used together
  * @Title: GtkTextTagTable
  *
+ * The collection of tags in a [class@Gtk.TextBuffer].
+ *
  * You may wish to begin by reading the
  * [text widget conceptual overview][TextWidget]
  * which gives an overview of all the objects and
diff --git a/gtk/gtktextview.c b/gtk/gtktextview.c
index 5b8bca680a..b3abee302c 100644
--- a/gtk/gtktextview.c
+++ b/gtk/gtktextview.c
@@ -63,12 +63,14 @@
  * @Title: GtkTextView
  * @See_also: #GtkTextBuffer, #GtkTextIter
  *
+ * A widget that displays the contents of a [class@Gtk.TextBuffer].
+ *
  * You may wish to begin by reading the
  * [text widget conceptual overview][TextWidget]
  * which gives an overview of all the objects and data
  * types related to the text widget and how they work together.
  *
- * # CSS nodes
+ * ## CSS nodes
  *
  * |[<!-- language="plain" -->
  * textview.view
@@ -91,7 +93,7 @@
  * If a context menu is opened, the window node will appear as a subnode
  * of the main node.
  *
- * # Accessibility
+ * ## Accessibility
  *
  * GtkTextView uses the #GTK_ACCESSIBLE_ROLE_TEXT_BOX role.
  */
diff --git a/gtk/gtktooltip.c b/gtk/gtktooltip.c
index a192d1eb0d..7755bdc8a7 100644
--- a/gtk/gtktooltip.c
+++ b/gtk/gtktooltip.c
@@ -40,6 +40,8 @@
  * @Short_description: Add tips to your widgets
  * @Title: GtkTooltip
  *
+ * An object representing a widget tooltip.
+ *
  * Basic tooltips can be realized simply by using gtk_widget_set_tooltip_text()
  * or gtk_widget_set_tooltip_markup() without any explicit tooltip object.
  *
diff --git a/gtk/gtktreeselection.h b/gtk/gtktreeselection.h
index 351b1a665a..40f46fac6d 100644
--- a/gtk/gtktreeselection.h
+++ b/gtk/gtktreeselection.h
@@ -40,9 +40,11 @@ G_BEGIN_DECLS
  * @data: (closure): user data
  *
  * A function used by gtk_tree_selection_set_select_function() to filter
- * whether or not a row may be selected.  It is called whenever a row's
- * state might change.  A return value of %TRUE indicates to @selection
- * that it is okay to change the selection.
+ * whether or not a row may be selected. It is called whenever a row's
+ * state might change.
+ *
+ * A return value of %TRUE indicates to @selection that it is okay to
+ * change the selection.
  *
  * Returns: %TRUE, if the selection state of the row can be toggled
  */
diff --git a/gtk/gtktreesortable.h b/gtk/gtktreesortable.h
index a0579829da..239f6ccb94 100644
--- a/gtk/gtktreesortable.h
+++ b/gtk/gtktreesortable.h
@@ -38,20 +38,18 @@ G_BEGIN_DECLS
 /**
  * GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID:
  *
- * The GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID can be used to make a
- * #GtkTreeSortable use the default sort function.
+ * Uses the default sort function in a [interface@Gtk.TreeSortable].
  *
- * See also gtk_tree_sortable_set_sort_column_id()
+ * See also: [method@Gtk.TreeSortable.set_sort_column_id]
  */
 #define GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID (-1)
 
 /**
  * GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID:
  *
- * The GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID can be used to make a
- * #GtkTreeSortable use no sorting.
+ * Disables sorting in a [interface@Gtk.TreeSortabke].
  *
- * See also gtk_tree_sortable_set_sort_column_id()
+ * See also: [method@Gtk.TreeSortable.set_sort_column_id]
  */
 #define GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID (-2)
 
@@ -68,7 +66,9 @@ typedef struct _GtkTreeSortableIface GtkTreeSortableIface;
  *
  * A GtkTreeIterCompareFunc should return a negative integer, zero, or a positive
  * integer if @a sorts before @b, @a sorts with @b, or @a sorts after @b
- * respectively. If two iters compare as equal, their order in the sorted model
+ * respectively.
+ *
+ * If two iters compare as equal, their order in the sorted model
  * is undefined. In order to ensure that the #GtkTreeSortable behaves as
  * expected, the GtkTreeIterCompareFunc must define a partial order on
  * the model, i.e. it must be reflexive, antisymmetric and transitive.
diff --git a/gtk/gtktreeviewcolumn.h b/gtk/gtktreeviewcolumn.h
index 7199636f24..cac13b4cdc 100644
--- a/gtk/gtktreeviewcolumn.h
+++ b/gtk/gtktreeviewcolumn.h
@@ -63,11 +63,13 @@ typedef enum
  * @data: (closure): user data
  *
  * A function to set the properties of a cell instead of just using the
- * straight mapping between the cell and the model.  This is useful for
- * customizing the cell renderer.  For example, a function might get an
- * integer from the @tree_model, and render it to the “text” attribute of
- * “cell” by converting it to its written equivalent.  This is set by
- * calling gtk_tree_view_column_set_cell_data_func()
+ * straight mapping between the cell and the model.
+ *
+ * This function is useful for customizing the cell renderer. For example,
+ * a function might get an* integer from the @tree_model, and render it to
+ * the “text” attribute of “cell” by converting it to its written equivalent.
+ *
+ * See also: gtk_tree_view_column_set_cell_data_func()
  */
 typedef void (* GtkTreeCellDataFunc) (GtkTreeViewColumn *tree_column,
                                      GtkCellRenderer   *cell,
diff --git a/gtk/gtkwidget.h b/gtk/gtkwidget.h
index 765cb207c3..53f218b133 100644
--- a/gtk/gtkwidget.h
+++ b/gtk/gtkwidget.h
@@ -62,11 +62,7 @@ typedef struct _GtkWidgetClassPrivate  GtkWidgetClassPrivate;
  * @width: the width of the widget’s allocated area.
  * @height: the height of the widget’s allocated area.
  *
- * A #GtkAllocation-struct of a widget represents region
- * which has been allocated to the widget by its parent. It is a subregion
- * of its parents allocation. See
- * [GtkWidget’s geometry management section][geometry-management] for
- * more information.
+ * The rectangle representing the area allocated for a widget by its parent.
  */
 typedef         GdkRectangle       GtkAllocation;