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

@@ -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,

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,

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().
  *

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)

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

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

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

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

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

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"

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

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

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
 {

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:

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.
  *

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

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;

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

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

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

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

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.
  */

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.
  *

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
  */

gtk/gtktreesortable.h

@@ -37,20 +37,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.TreeSortable].
  *
- * 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)
 
@@ -67,7 +65,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.

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,

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;