docs: Port various parts to gi-docgen annotations

So they properly show up in the docs. Part-of: <https://gitlab.gnome.org/GNOME/gnome-shell/-/merge_requests/3518>
2024-10-21 09:55:50 +02:00 · 2024-10-21 09:55:50 +02:00 · 38cca6279c
commit 38cca6279c
parent a79d517c12
41 changed files with 181 additions and 197 deletions
--- a/src/gtkactionmuxer.c
+++ b/src/gtkactionmuxer.c
@ -29,8 +29,9 @@
 #include <string.h>

 /**
- * SECTION:gtkactionmuxer
- * @short_description: Aggregate and monitor several action groups
+ * GtkActionMuxer:
+ *
+ * Aggregate and monitor several action groups
 *
 * #GtkActionMuxer is a #GActionGroup and #GtkActionObservable that is
 * capable of containing other #GActionGroup instances.
--- a/src/gtkactionobservable.c
+++ b/src/gtkactionobservable.c
@ -24,9 +24,9 @@
 G_DEFINE_INTERFACE (GtkActionObservable, gtk_action_observable, G_TYPE_OBJECT)

 /*
- * SECTION:gtkactionobserable
- * @short_description: an interface implemented by objects that report
- *                     changes to actions
+ * GtkActionObservable:
+ *
+ * An interface implemented by objects that report changes to actions
 */

 void
--- a/src/gtkactionobserver.c
+++ b/src/gtkactionobserver.c
@ -24,9 +24,10 @@
 G_DEFINE_INTERFACE (GtkActionObserver, gtk_action_observer, G_TYPE_OBJECT)

 /**
- * SECTION:gtkactionobserver
- * @short_description: an interface implemented by objects that are
- *                     interested in monitoring actions for changes
+ * GtkActionObserver:
+ *
+ * An interface implemented by objects that are interested in
+ * monitoring actions for changes
 *
 * GtkActionObserver is a simple interface allowing objects that wish to
 * be notified of changes to actions to be notified of those changes.
--- a/src/shell-app-cache.c
+++ b/src/shell-app-cache.c
@ -7,9 +7,9 @@
 #include "shell-global-private.h"

 /**
- * SECTION:shell-app-cache
- * @title: ShellAppCache
- * @short_description: application information cache
+ * ShellAppCache:
+ *
+ * Application information cache
 *
 * The #ShellAppCache is responsible for caching information about #GAppInfo
 * to ensure that the compositor thread never needs to perform disk reads to
--- a/src/shell-app-usage.c
+++ b/src/shell-app-usage.c
@ -24,8 +24,9 @@
 */

 /**
- * SECTION:shell-app-usage
- * @short_description: Track application usage/state data
+ * ShellAppUsage:
+ *
+ *Track application usage/state data
 *
 * This class maintains some usage and state statistics for
 * applications by keeping track of the approximate time an application's
--- a/src/shell-app.c
+++ b/src/shell-app.c
@ -57,8 +57,9 @@ typedef struct {
 } ShellAppRunningState;

 /**
- * SECTION:shell-app
- * @short_description: Object representing an application
+ * ShellApp:
+ *
+ * Object representing an application
 *
 * This object wraps a #GDesktopAppInfo, providing methods and signals
 * primarily useful for running applications.
--- a/src/shell-blur-effect.c
+++ b/src/shell-blur-effect.c
@ -25,8 +25,9 @@
 #include "shell-enum-types.h"

 /**
- * SECTION:shell-blur-effect
- * @short_description: Blur effect for actors
+ * ShellBlurEffect:
+ *
+ * Blur effect for actors
 *
 * #ShellBlurEffect is a blur implementation based on Clutter. It also has
 * an optional brightness property.
--- a/src/shell-glsl-effect.c
+++ b/src/shell-glsl-effect.c
@ -1,8 +1,9 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */

 /**
- * SECTION:shell-glsl-effect
- * @short_description: An offscreen effect using GLSL
+ * ShellGLSLEffect:
+ *
+ * An offscreen effect using GLSL
 *
 * A #ShellGLSLEffect is a #ClutterOffscreenEffect that allows
 * running custom GLSL to the vertex and fragment stages of the
--- a/src/shell-invert-lightness-effect.c
+++ b/src/shell-invert-lightness-effect.c
@ -20,10 +20,10 @@
 */

 /**
- * SECTION:shell-invert-lightness-effect
- * @short_description: A colorization effect where lightness is inverted but
+ * ShellInvertLightnessEffect:
+ *
+ * A colorization effect where lightness is inverted but
 * color is not.
- * @see_also: #ClutterEffect, #ClutterOffscreenEffect
 *
 * #ShellInvertLightnessEffect is a sub-class of #ClutterEffect that enhances
 * the appearance of a clutter actor.  Specifically it inverts the lightness
--- a/src/shell-perf-log.c
+++ b/src/shell-perf-log.c
@ -13,8 +13,9 @@ typedef union  _ShellPerfStatisticValue ShellPerfStatisticValue;
 typedef struct _ShellPerfBlock ShellPerfBlock;

 /**
- * SECTION:shell-perf-log
- * @short_description: Event recorder for performance measurement
+ * ShellPerfLog:
+ *
+ * Event recorder for performance measurement
 *
 * ShellPerfLog provides a way for different parts of the code to
 * record information for subsequent analysis and interactive
--- a/src/shell-screenshot.h
+++ b/src/shell-screenshot.h
@ -4,8 +4,9 @@
 #include <mtk/mtk.h>

 /**
- * SECTION:shell-screenshot
- * @short_description: Grabs screenshots of areas and/or windows
+ * ShellScreenshot:
+ *
+ * Grabs screenshots of areas and/or windows
 *
 * The #ShellScreenshot object is used to take screenshots of screen
 * areas or windows and write them out as png files.
--- a/src/shell-stack.c
+++ b/src/shell-stack.c
@ -1,8 +1,9 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */

 /**
- * SECTION:shell-stack
- * @short_description: Pure "Z-axis" container class
+ * ShellStack:
+ *
+ * Pure "Z-axis" container class
 *
 * A #ShellStack draws its children on top of each other,
 * aligned to the top left.  It will be sized in width/height
--- a/src/shell-window-tracker.c
+++ b/src/shell-window-tracker.c
@ -27,8 +27,9 @@
 */

 /**
- * SECTION:shell-window-tracker
- * @short_description: Associate windows with applications
+ * ShellWindowTracker:
+ *
+ * Associate windows with applications
 *
 * Maintains a mapping from windows to applications (.desktop file ids).
 * It currently implements this with some heuristics on the WM_CLASS X11
--- a/src/st/st-adjustment.c
+++ b/src/st/st-adjustment.c
@ -19,8 +19,9 @@
 */

 /**
- * SECTION:st-adjustment
- * @short_description: A GObject representing an adjustable bounded value
+ * StAdjustment:
+ *
+ * An adjustable bounded value.
 *
 * The #StAdjustment object represents a range of values bounded between a
 * minimum and maximum, together with step and page increments and a page size.
@ -526,7 +527,7 @@ st_adjustment_set_value (StAdjustment *adjustment,
 * @upper: the upper value
 *
 * Set #StAdjustment:value to a value clamped between @lower and @upper. The
- * clamping described by st_adjustment_set_value() still applies.
+ * clamping described by [method@St.Adjustment.set_value] still applies.
 */
 void
 st_adjustment_clamp_page (StAdjustment *adjustment,
@ -569,14 +570,14 @@ st_adjustment_clamp_page (StAdjustment *adjustment,
 * Sets the minimum value of the adjustment.
 *
 * When setting multiple adjustment properties via their individual
- * setters, multiple #GObject::notify and #StAdjustment::changed
+ * setters, multiple #GObject::notify and [signal@St.Adjustment::changed]
 * signals will be emitted. However, it’s possible to compress the
- * #GObject::notify and #StAdjustment::changed signals into one of each
+ * #GObject::notify and [signal@St.Adjustment::changed] signals into one of each
 * by calling g_object_freeze_notify() and g_object_thaw_notify() around the
 * calls to the individual setters.
 *
- * Alternatively, st_adjustment_set_values() can be used to compress
- * #GObject::notify and #StAdjustment::changed emissions.
+ * Alternatively, [method@St.Adjustment.set_values] can be used to compress
+ * #GObject::notify and [signal@St.Adjustment::changed] emissions.
 */
 static gboolean
 st_adjustment_set_lower (StAdjustment *adjustment,
@ -610,7 +611,7 @@ st_adjustment_set_lower (StAdjustment *adjustment,
 * Note that values will be restricted by `upper - page-size`
 * if the page-size property is nonzero.
 *
- * See st_adjustment_set_lower() about how to compress multiple
+ * See [method@St.Adjustment.set_lower] about how to compress multiple
 * signal emissions when setting multiple adjustment properties.
 *
 * Returns: %TRUE if the value was changed
@ -644,7 +645,7 @@ st_adjustment_set_upper (StAdjustment *adjustment,
 *
 * Sets the step increment of the adjustment.
 *
- * See st_adjustment_set_lower() about how to compress multiple
+ * See [method@St.Adjustment.set_lower] about how to compress multiple
 * signal emissions when setting multiple adjustment properties.
 *
 * Returns: %TRUE if the value was changed
@ -674,7 +675,7 @@ st_adjustment_set_step_increment (StAdjustment *adjustment,
 *
 * Sets the page increment of the adjustment.
 *
- * See st_adjustment_set_lower() about how to compress multiple
+ * See [method@St.Adjustment.set_lower] about how to compress multiple
 * signal emissions when setting multiple adjustment properties.
 *
 * Returns: %TRUE if the value was changed
@ -704,7 +705,7 @@ st_adjustment_set_page_increment (StAdjustment *adjustment,
 *
 * Sets the page size of the adjustment.
 *
- * See st_adjustment_set_lower() about how to compress multiple
+ * See [method@St.Adjustment.set_lower] about how to compress multiple
 * signal emissions when setting multiple adjustment properties.
 *
 * Returns: %TRUE if the value was changed
@ -744,9 +745,9 @@ st_adjustment_set_page_size (StAdjustment *adjustment,
 * Sets all properties of the adjustment at once.
 *
 * Use this function to avoid multiple emissions of the #GObject::notify and
- * #StAdjustment::changed signals. See st_adjustment_set_lower() for an
+ * [signal@St.Adjustment::changed] signals. See st_adjustment_set_lower() for an
 * alternative way of compressing multiple emissions of #GObject::notify and
- * #StAdjustmet::changed into one of each.
+ * [signal@St.Adjustment::changed] into one of each.
 */
 void
 st_adjustment_set_values (StAdjustment *adjustment,
@ -827,7 +828,7 @@ st_adjustment_get_values (StAdjustment *adjustment,
 *   or similar.
 *
 * Adjusts the adjustment using delta values from a scroll event.
- * You should use this instead of using st_adjustment_set_value()
+ * You should use this instead of using [method@St.Adjustment.set_value]
 * as this method will tweak the values directly using the same
 * math as GTK+, to ensure that scrolling is consistent across
 * the environment.
@ -910,7 +911,7 @@ on_transition_stopped (ClutterTransition *transition,
 * @name: a transition name
 *
 * Get the #ClutterTransition for @name previously added with
- * st_adjustment_add_transition() or %NULL if not found.
+ * [method@St.Adjustment.add_transition] or %NULL if not found.
 *
 * Returns: (transfer none) (nullable): a #ClutterTransition
 */
@ -942,7 +943,7 @@ st_adjustment_get_transition (StAdjustment *adjustment,
 * @transition: a #ClutterTransition
 *
 * Add a #ClutterTransition for the adjustment. If the transition stops, it will
- * be automatically removed if #ClutterTransition:remove-on-complete is %TRUE.
+ * be automatically removed if [property@Clutter.Transition:remove-on-complete] is %TRUE.
 */
 void
 st_adjustment_add_transition (StAdjustment      *adjustment,
@ -989,7 +990,7 @@ st_adjustment_add_transition (StAdjustment      *adjustment,
 * @adjustment: a #StAdjustment
 * @name: the name of the transition to remove
 *
- * Remove a #ClutterTransition previously added by st_adjustment_add_transtion()
+ * Remove a #ClutterTransition previously added by [method@St.Adjustment.add_transition]
 * with @name.
 */
 void
--- a/src/st/st-bin.c
+++ b/src/st/st-bin.c
@ -19,13 +19,12 @@
 */

 /**
- * SECTION:st-bin
- * @short_description: a simple container with one actor
+ * StBin:
+ *
+ * A simple container with one actor.
 *
 * #StBin is a simple container capable of having only one
 * #ClutterActor as a child.
- *
- * #StBin inherits from #StWidget, so it is fully themable.
 */

 #include "config.h"
--- a/src/st/st-box-layout.c
+++ b/src/st/st-box-layout.c
@ -35,8 +35,9 @@
 */

 /**
- * SECTION:st-box-layout
- * @short_description: a layout container arranging children in a single line
+ * StBoxLayout:
+ *
+ * Layout container arranging children in a single line.
 *
 * The #StBoxLayout arranges its children along a single line, where each
 * child can be allocated either its preferred size or larger if the expand
@ -44,7 +45,6 @@
 * than its requested size. If the fill option is not set, but the expand option
 * is enabled, then the position of the actor within the available space can
 * be determined by the alignment child property.
- *
 */

 #include <stdlib.h>
--- a/src/st/st-box-layout.h
+++ b/src/st/st-box-layout.h
@ -35,12 +35,6 @@ G_DECLARE_FINAL_TYPE (StBoxLayout, st_box_layout, ST, BOX_LAYOUT, StViewport)
 typedef struct _StBoxLayout StBoxLayout;
 typedef struct _StBoxLayoutPrivate StBoxLayoutPrivate;

-/**
- * StBoxLayout:
- *
- * The contents of this structure are private and should only be accessed
- * through the public API.
- */
 struct _StBoxLayout
 {
  /*< private >*/
--- a/src/st/st-button.c
+++ b/src/st/st-button.c
@ -20,8 +20,9 @@
 */

 /**
- * SECTION:st-button
- * @short_description: Button widget
+ * StButton:
+ *
+ * Button widget
 *
 * A button widget with support for either a text label or icon, toggle mode
 * and transitions effects between states.
--- a/src/st/st-clipboard.c
+++ b/src/st/st-clipboard.c
@ -18,8 +18,9 @@
 */

 /**
- * SECTION:st-clipboard
- * @short_description: a simple representation of the clipboard
+ * StClipboard:
+ *
+ * A simple representation of the clipboard
 *
 * #StCliboard is a very simple object representation of the clipboard
 * available to applications. Text is always assumed to be UTF-8 and non-text
--- a/src/st/st-clipboard.h
+++ b/src/st/st-clipboard.h
@ -33,12 +33,6 @@ G_DECLARE_FINAL_TYPE (StClipboard, st_clipboard, ST, CLIPBOARD, GObject)

 typedef struct _StClipboard StClipboard;

-/**
- * StClipboard:
- *
- * The contents of this structure is private and should only be accessed using
- * the provided API.
- */
 struct _StClipboard
 {
  /*< private >*/
--- a/src/st/st-drawing-area.c
+++ b/src/st/st-drawing-area.c
@ -19,16 +19,17 @@
 */

 /**
- * SECTION:st-drawing-area
- * @short_description: A dynamically-sized Cairo drawing area
+ * StDrawingArea:
+ *
+ * A dynamically-sized Cairo drawing area
 *
 * #StDrawingArea allows drawing via Cairo; the primary difference is that
- * it is dynamically sized. To use, connect to the #StDrawingArea::repaint
+ * it is dynamically sized. To use, connect to the [signal@St.DrawingArea::repaint]
 * signal, and inside the signal handler, call
- * st_drawing_area_get_context() to get the Cairo context to draw to.  The
- * #StDrawingArea::repaint signal will be emitted by default when the area is
+ * [method@St.DrawingArea.get_context] to get the Cairo context to draw to.  The
+ * [signal@St.DrawingArea::repaint] signal will be emitted by default when the area is
 * resized or the CSS style changes; you can use the
- * st_drawing_area_queue_repaint() as well.
+ * [method@St.DrawingArea.queue_repaint] as well.
 */

 #include "st-drawing-area.h"
@ -279,7 +280,7 @@ st_drawing_area_emit_repaint (StDrawingArea *area)
 * st_drawing_area_queue_repaint:
 * @area: the #StDrawingArea
 *
- * Will cause the actor to emit a #StDrawingArea::repaint signal before it is
+ * Will cause the actor to emit a [signal@St.DrawingArea::repaint] signal before it is
 * next drawn to the scene. Useful if some parameters for the area being
 * drawn other than the size or style have changed. Note that
 * clutter_actor_queue_redraw() will simply result in the same
@ -308,13 +309,13 @@ st_drawing_area_queue_repaint (StDrawingArea *area)
 * @area: the #StDrawingArea
 *
 * Gets the Cairo context to paint to. This function must only be called
- * from a signal handler or virtual function for the #StDrawingArea::repaint
+ * from a signal handler or virtual function for the [signal@St.DrawingArea::repaint]
 * signal.
 *
 * JavaScript code must call the special dispose function before returning from
 * the signal handler or virtual function to avoid leaking memory:
 *
- * |[<!-- language="JavaScript" -->
+ * ```js
 * function onRepaint(area) {
 *     let cr = area.get_context();
 *
@ -325,7 +326,7 @@ st_drawing_area_queue_repaint (StDrawingArea *area)
 *
 * let area = new St.DrawingArea();
 * area.connect('repaint', onRepaint);
- * ]|
+ * ```
 *
 * Returns: (transfer none): the Cairo context for the paint operation
 */
--- a/src/st/st-entry.c
+++ b/src/st/st-entry.c
@ -20,8 +20,9 @@
 */

 /**
- * SECTION:st-entry
- * @short_description: Widget for displaying text
+ * StEntry:
+ *
+ * Widget for displaying text
 *
 * #StEntry is a simple widget for displaying text. It derives from
 * #StWidget to add extra style and placement functionality over
--- a/src/st/st-focus-manager.c
+++ b/src/st/st-focus-manager.c
@ -19,8 +19,9 @@
 */

 /**
- * SECTION:st-focus-manager
- * @short_description: Keyboard focus management
+ * StFocusManager:
+ *
+ * Keyboard focus management
 *
 * #StFocusManager handles keyboard focus for all actors on the stage.
 */
--- a/src/st/st-generic-accessible.c
+++ b/src/st/st-generic-accessible.c
@ -18,9 +18,9 @@
 */

 /**
- * SECTION:st-generic-accessible
- * @short_description: An accessible class with signals for
- * implementing specific Atk interfaces
+ * StGenericAccessible:
+ *
+ * An accessible class with signals for implementing specific Atk interfaces
 *
 * #StGenericAccessible is mainly a workaround for the current lack of
 * of a proper support for GValue at javascript. See bug#703412 for
--- a/src/st/st-icon-theme.c
+++ b/src/st/st-icon-theme.c
@ -34,9 +34,9 @@
 #define DEFAULT_ICON_THEME "Adwaita"

 /**
- * SECTION:sticontheme
- * @Short_description: Looking up icons by name
- * @Title: StIconTheme
+ * StIconTheme:
+ *
+ * Looking up icons by name
 *
 * #StIconTheme provides a facility for looking up icons by name
 * and size. The main reason for using a name rather than simply
@ -1552,18 +1552,17 @@ choose_icon (StIconTheme       *icon_theme,
 * Looks up a named icon and returns a #StIconInfo containing
 * information such as the filename of the icon. The icon
 * can then be rendered into a pixbuf using
- * st_icon_info_load_icon(). (st_icon_theme_load_icon()
+ * [method@St.IconInfo.load_icon]. ([method@St.IconTheme.load_icon]
 * combines these two steps if all you need is the pixbuf.)
 *
 * When rendering on displays with high pixel densities you should not
 * use a @size multiplied by the scaling factor returned by functions
 * like gdk_window_get_scale_factor(). Instead, you should use
- * st_icon_theme_lookup_icon_for_scale(), as the assets loaded
+ * [method@St.IconTheme.lookup_by_gicon_for_scale], as the assets loaded
 * for a given scaling factor may be different.
 *
 * Returns: (nullable) (transfer full): a #StIconInfo object
- *     containing information about the icon, or %NULL if the
- *     icon wasn’t found.
+ *     containing information about the icon.
 */
 StIconInfo *
 st_icon_theme_lookup_icon (StIconTheme       *icon_theme,
@ -1593,12 +1592,11 @@ st_icon_theme_lookup_icon (StIconTheme       *icon_theme,
 * Looks up a named icon for a particular window scale and returns a
 * #StIconInfo containing information such as the filename of the
 * icon. The icon can then be rendered into a pixbuf using
- * st_icon_info_load_icon(). (st_icon_theme_load_icon() combines
+ * [method@St.IconInfo.load_icon]. ([method@St.IconTheme.load_icon] combines
 * these two steps if all you need is the pixbuf.)
 *
 * Returns: (nullable) (transfer full): a #StIconInfo object
- *     containing information about the icon, or %NULL if the
- *     icon wasn’t found.
+ *     containing information about the icon.
 */
 StIconInfo *
 st_icon_theme_lookup_icon_for_scale (StIconTheme       *icon_theme,
@ -1691,7 +1689,7 @@ st_icon_theme_lookup_icon_for_scale (StIconTheme       *icon_theme,
 * Looks up a named icon and returns a #StIconInfo containing
 * information such as the filename of the icon. The icon
 * can then be rendered into a pixbuf using
- * st_icon_info_load_icon(). (st_icon_theme_load_icon()
+ * [method@St.IconInfo.load_icon]. ([method@St.IconTheme.load_icon]
 * combines these two steps if all you need is the pixbuf.)
 *
 * If @icon_names contains more than one name, this function
@ -1699,8 +1697,7 @@ st_icon_theme_lookup_icon_for_scale (StIconTheme       *icon_theme,
 * inherited icon themes.
 *
 * Returns: (nullable) (transfer full): a #StIconInfo object
- * containing information about the icon, or %NULL if the icon wasn’t
- * found.
+ * containing information about the icon
 */
 StIconInfo *
 st_icon_theme_choose_icon (StIconTheme       *icon_theme,
@ -1729,7 +1726,7 @@ st_icon_theme_choose_icon (StIconTheme       *icon_theme,
 * Looks up a named icon for a particular window scale and returns
 * a #StIconInfo containing information such as the filename of the
 * icon. The icon can then be rendered into a pixbuf using
- * st_icon_info_load_icon(). (st_icon_theme_load_icon()
+ * [method@St.IconInfo.load_icon]. ([method@St.IconTheme.load_icon]
 * combines these two steps if all you need is the pixbuf.)
 *
 * If @icon_names contains more than one name, this function
@ -1737,8 +1734,7 @@ st_icon_theme_choose_icon (StIconTheme       *icon_theme,
 * inherited icon themes.
 *
 * Returns: (nullable) (transfer full): a #StIconInfo object
- *     containing information about the icon, or %NULL if the
- *     icon wasn’t found.
+ *     containing information about the icon.
 */
 StIconInfo *
 st_icon_theme_choose_icon_for_scale (StIconTheme       *icon_theme,
@ -1770,7 +1766,7 @@ st_icon_theme_error_quark (void)
 * @icon_theme: a #StIconTheme
 * @icon_name: the name of the icon to lookup
 * @size: the desired icon size. The resulting icon may not be
- *     exactly this size; see st_icon_info_load_icon().
+ *     exactly this size.
 * @flags: flags modifying the behavior of the icon lookup
 * @error: (allow-none): Location to store error information on failure,
 *     or %NULL.
@ -1778,7 +1774,7 @@ st_icon_theme_error_quark (void)
 * Looks up an icon in an icon theme, scales it to the given size
 * and renders it into a pixbuf. This is a convenience function;
 * if more details about the icon are needed, use
- * st_icon_theme_lookup_icon() followed by st_icon_info_load_icon().
+ * [method@St.IconTheme.lookup_icon] followed by [method@St.IconInfo.load_icon].
 *
 * Note that you probably want to listen for icon theme changes and
 * update the icon. This is usually done by connecting to the
@ -1790,8 +1786,7 @@ st_icon_theme_error_quark (void)
 *
 * Returns: (nullable) (transfer full): the rendered icon; this may be
 *     a newly created icon or a new reference to an internal icon, so
- *     you must not modify the icon. Use g_object_unref() to release
- *     your reference to the icon. %NULL if the icon isn’t found.
+ *     you must not modify the icon.
 */
 GdkPixbuf *
 st_icon_theme_load_icon (StIconTheme       *icon_theme,
@ -1815,7 +1810,7 @@ st_icon_theme_load_icon (StIconTheme       *icon_theme,
 * @icon_theme: a #StIconTheme
 * @icon_name: the name of the icon to lookup
 * @size: the desired icon size. The resulting icon may not be
- *     exactly this size; see st_icon_info_load_icon().
+ *     exactly this size.
 * @scale: desired scale
 * @flags: flags modifying the behavior of the icon lookup
 * @error: (allow-none): Location to store error information on failure,
@ -1824,8 +1819,8 @@ st_icon_theme_load_icon (StIconTheme       *icon_theme,
 * Looks up an icon in an icon theme for a particular window scale,
 * scales it to the given size and renders it into a pixbuf. This is a
 * convenience function; if more details about the icon are needed,
- * use st_icon_theme_lookup_icon() followed by
- * st_icon_info_load_icon().
+ * use [method@St.IconTheme.lookup_icon] followed by
+ * [method@St.IconInfo.load_icon].
 *
 * Note that you probably want to listen for icon theme changes and
 * update the icon. This is usually done by connecting to the
@ -1837,8 +1832,7 @@ st_icon_theme_load_icon (StIconTheme       *icon_theme,
 *
 * Returns: (nullable) (transfer full): the rendered icon; this may be
 *     a newly created icon or a new reference to an internal icon, so
- *     you must not modify the icon. Use g_object_unref() to release
- *     your reference to the icon. %NULL if the icon isn’t found.
+ *     you must not modify the icon.
 */
 GdkPixbuf *
 st_icon_theme_load_icon_for_scale (StIconTheme       *icon_theme,
@ -2894,8 +2888,9 @@ st_icon_info_class_init (StIconInfoClass *klass)
 * st_icon_info_get_base_size:
 * @icon_info: a #StIconInfo
 *
- * Gets the base size for the icon. The base size
- * is a size for the icon that was specified by
+ * Gets the base size for the icon.
+ *
+ * The base size is a size for the icon that was specified by
 * the icon theme creator. This may be different
 * than the actual size of image; an example of
 * this is small emblem icons that can be attached
@ -2921,11 +2916,12 @@ st_icon_info_get_base_size (StIconInfo *icon_info)
 * st_icon_info_get_base_scale:
 * @icon_info: a #StIconInfo
 *
- * Gets the base scale for the icon. The base scale is a scale
- * for the icon that was specified by the icon theme creator.
- * For instance an icon drawn for a high-dpi screen with window
- * scale 2 for a base size of 32 will be 64 pixels tall and have
- * a base scale of 2.
+ * Gets the base scale for the icon.
+ *
+ * The base scale is a scale for the icon that was specified by
+ * the icon theme creator. For instance an icon drawn for a
+ * high-dpi screen with window scale 2 for a base size of 32 will be
+ * 64 pixels tall and have a base scale of 2.
 *
 * Returns: the base scale
 */
@ -2943,7 +2939,7 @@ st_icon_info_get_base_scale (StIconInfo *icon_info)
 *
 * Gets the filename for the icon.
 *
- * Returns: (nullable) (type filename): the filename for the icon, or %NULL.
+ * Returns: (nullable) (type filename): the filename for the icon.
 *     The return value is owned by GTK+ and should not be modified
 *     or freed.
 */
@ -2959,8 +2955,10 @@ st_icon_info_get_filename (StIconInfo *icon_info)
 * st_icon_info_is_symbolic:
 * @icon_info: a #StIconInfo
 *
- * Checks if the icon is symbolic or not. This currently uses only
- * the file name and not the file contents for determining this.
+ * Checks if the icon is symbolic or not.
+ *
+ * This currently uses only the file name and not
+ * the file contents for determining this.
 * This behaviour may change in the future.
 *
 * Returns: %TRUE if the icon is symbolic, %FALSE otherwise
@ -3411,13 +3409,13 @@ proxy_pixbuf_destroy (guchar *pixels, gpointer data)

 /**
 * st_icon_info_load_icon:
- * @icon_info: a #StIconInfo from st_icon_theme_lookup_icon()
+ * @icon_info: a #StIconInfo
 * @error: (allow-none): location to store error information on failure,
 *     or %NULL.
 *
 * Renders an icon previously looked up in an icon theme using
- * st_icon_theme_lookup_icon(); the size will be based on the size
- * passed to st_icon_theme_lookup_icon(). Note that the resulting
+ * [method@St.IconTheme.lookup_icon]; the size will be based on the size
+ * passed to [method@St.IconTheme.lookup_icon]. Note that the resulting
 * pixbuf may not be exactly this size; an icon theme may have icons
 * that differ slightly from their nominal sizes, and in addition GTK+
 * will avoid scaling icons that it considers sufficiently close to the
@ -3494,16 +3492,16 @@ load_icon_thread  (GTask        *task,

 /**
 * st_icon_info_load_icon_async:
- * @icon_info: a #StIconInfo from st_icon_theme_lookup_icon()
+ * @icon_info: a #StIconInfo
 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
 * @callback: (scope async): a #GAsyncReadyCallback to call when the
 *     request is satisfied
 * @user_data: (closure): the data to pass to callback function
 *
 * Asynchronously load, render and scale an icon previously looked up
- * from the icon theme using st_icon_theme_lookup_icon().
+ * from the icon theme using [method@St.IconTheme.lookup_icon].
 *
- * For more details, see st_icon_info_load_icon() which is the synchronous
+ * For more details, see [method@St.IconInfo.load_icon] which is the synchronous
 * version of this call.
 */
 void
@ -3539,7 +3537,7 @@ st_icon_info_load_icon_async (StIconInfo          *icon_info,

 /**
 * st_icon_info_load_icon_finish:
- * @icon_info: a #StIconInfo from st_icon_theme_lookup_icon()
+ * @icon_info: a #StIconInfo
 * @res: a #GAsyncResult
 * @error: (allow-none): location to store error information on failure,
 *     or %NULL.
@ -3938,7 +3936,7 @@ st_icon_info_load_symbolic_internal (StIconInfo     *icon_info,
 *
 * Loads an icon, modifying it to match the system colours for the foreground,
 * success, warning and error colors provided. If the icon is not a symbolic
- * one, the function will return the result from st_icon_info_load_icon().
+ * one, the function will return the result from [method@St.IconInfo.load_icon].
 *
 * This allows loading symbolic icons that will match the system theme.
 *
@ -4036,7 +4034,7 @@ load_symbolic_icon_thread (GTask        *task,

 /**
 * st_icon_info_load_symbolic_async:
- * @icon_info: a #StIconInfo from st_icon_theme_lookup_icon()
+ * @icon_info: a #StIconInfo
 * @colors: an #StIconColors representing the foreground, error and
 *     success colors of the icon
 * @cancellable: (allow-none): optional #GCancellable object,
@ -4046,7 +4044,7 @@ load_symbolic_icon_thread (GTask        *task,
 * @user_data: (closure): the data to pass to callback function
 *
 * Asynchronously load, render and scale a symbolic icon previously looked up
- * from the icon theme using st_icon_theme_lookup_icon().
+ * from the icon theme using [method@St.IconTheme.lookup_icon].
 *
 * For more details, see st_icon_info_load_symbolic() which is the synchronous
 * version of this call.
@ -4097,7 +4095,7 @@ st_icon_info_load_symbolic_async (StIconInfo          *icon_info,

 /**
 * st_icon_info_load_symbolic_finish:
- * @icon_info: a #StIconInfo from st_icon_theme_lookup_icon()
+ * @icon_info: a #StIconInfo
 * @res: a #GAsyncResult
 * @was_symbolic: (out) (allow-none): a #gboolean, returns whether the
 *     loaded icon was a symbolic one and whether the @fg color was
@ -4160,17 +4158,16 @@ st_icon_info_load_symbolic_finish (StIconInfo    *icon_info,
 *
 * Looks up an icon and returns a #StIconInfo containing information
 * such as the filename of the icon. The icon can then be rendered
- * into a pixbuf using st_icon_info_load_icon().
+ * into a pixbuf using [method@St.IconInfo.load_icon].
 *
 * When rendering on displays with high pixel densities you should not
 * use a @size multiplied by the scaling factor returned by functions
 * like gdk_window_get_scale_factor(). Instead, you should use
- * st_icon_theme_lookup_by_gicon_for_scale(), as the assets loaded
+ * [method@St.IconTheme.lookup_by_gicon_for_scale], as the assets loaded
 * for a given scaling factor may be different.
 *
 * Returns: (nullable) (transfer full): a #StIconInfo containing
- *     information about the icon, or %NULL if the icon wasn’t
- *     found. Unref with g_object_unref()
+ *     information about the icon.
 */
 StIconInfo *
 st_icon_theme_lookup_by_gicon (StIconTheme       *icon_theme,
@ -4193,11 +4190,10 @@ st_icon_theme_lookup_by_gicon (StIconTheme       *icon_theme,
 *
 * Looks up an icon and returns a #StIconInfo containing information
 * such as the filename of the icon. The icon can then be rendered into
- * a pixbuf using st_icon_info_load_icon().
+ * a pixbuf using [method@St.IconInfo.load_icon].
 *
 * Returns: (nullable) (transfer full): a #StIconInfo containing
- *     information about the icon, or %NULL if the icon wasn’t
- *     found. Unref with g_object_unref()
+ *     information about the icon.
 */
 StIconInfo *
 st_icon_theme_lookup_by_gicon_for_scale (StIconTheme       *icon_theme,
--- a/src/st/st-icon-theme.h
+++ b/src/st/st-icon-theme.h
@ -54,7 +54,7 @@ G_DECLARE_FINAL_TYPE (StIconTheme, st_icon_theme, ST, ICON_THEME, GObject)
 * @ST_ICON_LOOKUP_DIR_RTL: Try to load a variant of the icon for right-to-left
 *   text direction.
 *
- * Used to specify options for st_icon_theme_lookup_icon()
+ * Used to specify options for [method@St.IconTheme.lookup_icon]
 */
 typedef enum
 {
--- a/src/st/st-icon.c
+++ b/src/st/st-icon.c
@ -19,8 +19,9 @@
 */

 /**
- * SECTION:st-icon
- * @short_description: a simple styled icon actor
+ * StIcon:
+ *
+ * A simple styled icon actor
 *
 * #StIcon is a simple styled texture actor that displays an image from
 * a stylesheet.
--- a/src/st/st-icon.h
+++ b/src/st/st-icon.h
@ -40,12 +40,6 @@ G_DECLARE_FINAL_TYPE (StIcon, st_icon, ST, ICON, StWidget)

 typedef struct _StIconPrivate       StIconPrivate;

-/**
- * StIcon:
- *
- * The contents of this structure are private and should only be accessed
- * through the public API.
- */
 struct _StIcon {
  /*< private >*/
  StWidget parent;
--- a/src/st/st-label.c
+++ b/src/st/st-label.c
@ -20,8 +20,9 @@
 */

 /**
- * SECTION:st-label
- * @short_description: Widget for displaying text
+ * StLabel:
+ *
+ * Widget for displaying text
 *
 * #StLabel is a simple widget for displaying text. It derives from
 * #StWidget to add extra style and placement functionality over
--- a/src/st/st-label.h
+++ b/src/st/st-label.h
@ -32,12 +32,6 @@ G_DECLARE_FINAL_TYPE (StLabel, st_label, ST, LABEL, StWidget)

 typedef struct _StLabelPrivate       StLabelPrivate;

-/**
- * StLabel:
- *
- * The contents of this structure is private and should only be accessed using
- * the provided API.
- */
 struct _StLabel
 {
  /*< private >*/
--- a/src/st/st-scroll-bar.c
+++ b/src/st/st-scroll-bar.c
@ -21,8 +21,9 @@
 */

 /**
- * SECTION:st-scroll-bar
- * @short_description: a user interface element to control scrollable areas.
+ * StScrollBar:
+ *
+ * A user interface element to control scrollable areas.
 *
 * The #StScrollBar allows users to scroll scrollable actors, either by
 * the step or page amount, or by manually dragging the handle.
--- a/src/st/st-scroll-view.c
+++ b/src/st/st-scroll-view.c
@ -21,8 +21,9 @@
 */

 /**
- * SECTION:st-scroll-view
- * @short_description: a container for scrollable children
+ * StScrollView:
+ *
+ * Container for scrollable children
 *
 * #StScrollView is a single child container for actors that implement
 * #StScrollable. It provides scrollbars around the edge of the child to
--- a/src/st/st-scrollable.c
+++ b/src/st/st-scrollable.c
@ -25,8 +25,9 @@
 G_DEFINE_INTERFACE (StScrollable, st_scrollable, G_TYPE_OBJECT)

 /**
- * SECTION:st-scrollable
- * @short_description: A #ClutterActor that can be scrolled
+ * StScrollable:
+ *
+ * A #ClutterActor that can be scrolled
 *
 * The #StScrollable interface is exposed by actors that support scrolling.
 *
@ -96,7 +97,7 @@ st_scrollable_default_init (StScrollableInterface *g_iface)
       *
       * JavaScript code may override this as demonstrated below:
       *
-       * |[<!-- language="JavaScript" -->
+       * ```js
       * export const MyScrollable = GObject.registerClass({
       *     Properties: {
       *         'hadjustment': GObject.ParamSpec.override(
@ -118,7 +119,7 @@ st_scrollable_default_init (StScrollableInterface *g_iface)
       *         this.notify('hadjustment');
       *     }
       * });
-       * ]|
+       * ```
       */
      g_object_interface_install_property (g_iface,
                                           g_param_spec_object ("hadjustment", NULL, NULL,
--- a/src/st/st-shadow.c
+++ b/src/st/st-shadow.c
@ -26,16 +26,6 @@
 G_DEFINE_BOXED_TYPE (StShadow, st_shadow, st_shadow_ref, st_shadow_unref)
 G_DEFINE_BOXED_TYPE (StShadowHelper, st_shadow_helper, st_shadow_helper_copy, st_shadow_helper_free)

-/**
- * SECTION: st-shadow
- * @short_description: Boxed type for -st-shadow attributes
- *
- * #StShadow is a boxed type for storing attributes of the -st-shadow
- * property, modelled liberally after the CSS3 box-shadow property.
- * See http://www.css3.info/preview/box-shadow/
- *
- */
-
 /**
 * st_shadow_new:
 * @color: shadow's color
@ -178,9 +168,9 @@ st_shadow_get_box (StShadow              *shadow,
 }

 /**
- * SECTION: st-shadow-helper
+ * StShadowHelper:
 *
- * An helper for implementing a drop shadow on a actor.
+ * A helper for implementing a drop shadow on a actor.
 * The actor is expected to recreate the helper whenever its contents
 * or size change. Then, it would call st_shadow_helper_paint() inside
 * its paint() virtual function.
--- a/src/st/st-shadow.h
+++ b/src/st/st-shadow.h
@ -41,7 +41,11 @@ typedef struct _StShadowHelper StShadowHelper;
 * @spread: shadow's spread radius - grow the shadow without enlarging the
 *           blur.
 *
- * Attributes of the -st-shadow property.
+ * A type representing -st-shadow attributes
+ *
+ * #StShadow is a boxed type for storing attributes of the -st-shadow
+ * property, modelled liberally after the CSS3 box-shadow property.
+ * See http://www.css3.info/preview/box-shadow/
 */
 struct _StShadow {
    CoglColor color;
--- a/src/st/st-theme-context.h
+++ b/src/st/st-theme-context.h
@ -28,8 +28,9 @@
 G_BEGIN_DECLS

 /**
- * SECTION:st-theme-context
- * @short_description: holds global information about a tree of styled objects
+ * StThemeContext:
+ *
+ * Holds global information about a tree of styled objects
 *
 * #StThemeContext is responsible for managing information global to a tree of styled objects,
 * such as the set of stylesheets or the default font. In normal usage, a #StThemeContext
--- a/src/st/st-theme-node.h
+++ b/src/st/st-theme-node.h
@ -30,8 +30,9 @@
 G_BEGIN_DECLS

 /**
- * SECTION:st-theme-node
- * @short_description: style information for one node in a tree of themed objects
+ * StThemeNode:
+ *
+ * Style information for one node in a tree of themed objects
 *
 * A #StThemeNode represents the CSS style information (the set of CSS properties) for one
 * node in a tree of themed objects. In typical usage, it represents the style information
--- a/src/st/st-theme.h
+++ b/src/st/st-theme.h
@ -26,8 +26,9 @@
 G_BEGIN_DECLS

 /**
- * SECTION:st-theme
- * @short_description: a set of stylesheets
+ * StTheme:
+ *
+ * A set of stylesheets
 *
 * #StTheme holds a set of stylesheets. (The "cascade" of the name
 * Cascading Stylesheets.) A #StTheme can be set to apply to all the actors
--- a/src/st/st-types.h
+++ b/src/st/st-types.h
@ -26,13 +26,6 @@

 G_BEGIN_DECLS

-/**
- * SECTION:st-types
- * @short_description: type definitions used throughout St
- *
- * Common types for StWidgets.
- */
-
 typedef enum {
  ST_BACKGROUND_SIZE_AUTO,
  ST_BACKGROUND_SIZE_CONTAIN,
--- a/src/st/st-viewport.c
+++ b/src/st/st-viewport.c
@ -36,8 +36,9 @@
 */

 /**
- * SECTION:st-viewport
- * @short_description: a scrollable container
+ * StViewport:
+ *
+ * Scrollable container
 *
 * The #StViewport is a generic #StScrollable implementation.
 *
--- a/src/st/st-widget.c
+++ b/src/st/st-widget.c
@ -86,11 +86,12 @@ struct _StWidgetPrivate
 };

 /**
- * SECTION:st-widget
- * @short_description: Base class for stylable actors
+ * StWidget:
+ *
+ * Base class for stylable actors
 *
 * #StWidget is a simple abstract class on top of #ClutterActor. It
- * provides basic themeing properties.
+ * provides basic theming properties.
 *
 * Actors in the St library should subclass #StWidget if they plan
 * to obey to a certain #StStyle.
@ -2675,7 +2676,7 @@ check_labels (StWidget *widget)
 *
 * Gets a list of the focusable children of @widget, in "Tab"
 * order. By default, this returns all visible
- * (as in clutter_actor_is_visible()) children of @widget.
+ * (as in [method@Clutter.Actor.is_visible]) children of @widget.
 *
 * Returns: (element-type Clutter.Actor) (transfer container):
 *   @widget's focusable children