diff --git a/src/gtkactionmuxer.c b/src/gtkactionmuxer.c
index 16fade25a..ec0f20ee9 100644
--- 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.
diff --git a/src/gtkactionobservable.c b/src/gtkactionobservable.c
index ab90df2e5..1173bdc5a 100644
--- 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
diff --git a/src/gtkactionobserver.c b/src/gtkactionobserver.c
index 3287106b7..c8fe09afb 100644
--- 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.
diff --git a/src/shell-app-cache.c b/src/shell-app-cache.c
index ef1075451..484e0248c 100644
--- 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
diff --git a/src/shell-app-usage.c b/src/shell-app-usage.c
index ad40040d9..9e57a91b2 100644
--- 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
diff --git a/src/shell-app.c b/src/shell-app.c
index d413ea245..0b55aa092 100644
--- 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.
diff --git a/src/shell-blur-effect.c b/src/shell-blur-effect.c
index 1bcd8ba47..c5c5f4688 100644
--- 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.
diff --git a/src/shell-glsl-effect.c b/src/shell-glsl-effect.c
index 48eba31fb..d81fae3f7 100644
--- 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
diff --git a/src/shell-invert-lightness-effect.c b/src/shell-invert-lightness-effect.c
index 897973293..ac6081e36 100644
--- 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
diff --git a/src/shell-perf-log.c b/src/shell-perf-log.c
index 3bd5228a0..b2c8591e8 100644
--- 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
diff --git a/src/shell-screenshot.h b/src/shell-screenshot.h
index 248d34fea..c67587917 100644
--- 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.
diff --git a/src/shell-stack.c b/src/shell-stack.c
index 79841e074..f4fe4a450 100644
--- 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
diff --git a/src/shell-window-tracker.c b/src/shell-window-tracker.c
index 3704e7b31..0a048cccc 100644
--- 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
diff --git a/src/st/st-adjustment.c b/src/st/st-adjustment.c
index 189b70abb..b9d6d592e 100644
--- 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
diff --git a/src/st/st-bin.c b/src/st/st-bin.c
index 5a2847854..1ed58d334 100644
--- 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"
diff --git a/src/st/st-box-layout.c b/src/st/st-box-layout.c
index 75e780d19..af7ac455b 100644
--- 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>
diff --git a/src/st/st-box-layout.h b/src/st/st-box-layout.h
index f268d8027..37dec6d8c 100644
--- 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 >*/
diff --git a/src/st/st-button.c b/src/st/st-button.c
index f379f131b..448554b21 100644
--- 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.
diff --git a/src/st/st-clipboard.c b/src/st/st-clipboard.c
index 4867b1306..3ae697445 100644
--- 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
diff --git a/src/st/st-clipboard.h b/src/st/st-clipboard.h
index 67d2e2b14..becd10b4c 100644
--- 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 >*/
diff --git a/src/st/st-drawing-area.c b/src/st/st-drawing-area.c
index a9ffb6b16..d947af7ca 100644
--- 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
  */
diff --git a/src/st/st-entry.c b/src/st/st-entry.c
index 2aa72bd2d..8a773586d 100644
--- 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
diff --git a/src/st/st-focus-manager.c b/src/st/st-focus-manager.c
index 948a9dcce..a39845d9f 100644
--- 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.
  */
diff --git a/src/st/st-generic-accessible.c b/src/st/st-generic-accessible.c
index 3d51b0210..d830a84e0 100644
--- 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
diff --git a/src/st/st-icon-theme.c b/src/st/st-icon-theme.c
index dac3457b1..7223c33ab 100644
--- 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,
diff --git a/src/st/st-icon-theme.h b/src/st/st-icon-theme.h
index 5353572dd..d4c5e176c 100644
--- 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
 {
diff --git a/src/st/st-icon.c b/src/st/st-icon.c
index 620916867..546f620ca 100644
--- 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.
diff --git a/src/st/st-icon.h b/src/st/st-icon.h
index f80c5b4cc..8c73bd1e6 100644
--- 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;
diff --git a/src/st/st-label.c b/src/st/st-label.c
index f39cf6fce..05b9af556 100644
--- 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
diff --git a/src/st/st-label.h b/src/st/st-label.h
index 504a78a13..199a5a006 100644
--- 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 >*/
diff --git a/src/st/st-scroll-bar.c b/src/st/st-scroll-bar.c
index bdbaa1698..69f979277 100644
--- 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.
diff --git a/src/st/st-scroll-view.c b/src/st/st-scroll-view.c
index 5ead40977..11cf1744f 100644
--- 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
diff --git a/src/st/st-scrollable.c b/src/st/st-scrollable.c
index f8c49f37e..e203792a7 100644
--- 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,
diff --git a/src/st/st-shadow.c b/src/st/st-shadow.c
index c7d1aa932..0e7908ac1 100644
--- 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.
diff --git a/src/st/st-shadow.h b/src/st/st-shadow.h
index 5075bf2ac..bcdd4e177 100644
--- 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;
diff --git a/src/st/st-theme-context.h b/src/st/st-theme-context.h
index 96bbd76a3..edc1aa060 100644
--- 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
diff --git a/src/st/st-theme-node.h b/src/st/st-theme-node.h
index c34fac133..683b5f21d 100644
--- 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
diff --git a/src/st/st-theme.h b/src/st/st-theme.h
index af595db0b..f9d0ecca1 100644
--- 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
diff --git a/src/st/st-types.h b/src/st/st-types.h
index 52731978e..5c208c571 100644
--- 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,
diff --git a/src/st/st-viewport.c b/src/st/st-viewport.c
index 8b3ca153f..4f77b6c6c 100644
--- 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.
  *
diff --git a/src/st/st-widget.c b/src/st/st-widget.c
index 797d629d1..025da73f6 100644
--- 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