mutter: Cleanup gi-docgen annotationsbilelmoussaoui/mutter-docs

62 files changed, 290 insertions, 287 deletions

diff --git a/src/backends/meta-backend.c b/src/backends/meta-backend.c
index e77b9612b..b6538b45c 100644
--- a/src/backends/meta-backend.c
+++ b/src/backends/meta-backend.c
@@ -23,9 +23,9 @@
  */
 
 /**
- * SECTION:meta-backend
- * @title: MetaBackend
- * @short_description: Handles monitor config, modesetting, cursor sprites, ...
+ * MetaBackend:
+ * 
+ * Handles monitor config, modesetting, cursor sprites, ...
  *
  * MetaBackend is the abstraction that deals with several things like:
  * - Modesetting (depending on the backend, this can be done either by X or KMS)
diff --git a/src/backends/meta-barrier.c b/src/backends/meta-barrier.c
index dfcf5c41e..098141f96 100644
--- a/src/backends/meta-barrier.c
+++ b/src/backends/meta-barrier.c
@@ -1,9 +1,9 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; c-basic-offset: 2; -*- */
 
 /**
- * SECTION:barrier
- * @Title: MetaBarrier
- * @Short_Description: Pointer barriers
+ * MetaBarrier:
+ * 
+ * Pointer barriers
  */
 
 #include "config.h"
diff --git a/src/backends/meta-color-manager.c b/src/backends/meta-color-manager.c
index 6bc2ba292..dd9336c55 100644
--- a/src/backends/meta-color-manager.c
+++ b/src/backends/meta-color-manager.c
@@ -17,10 +17,10 @@
  */
 
 /**
- * SECTION:meta-color-manager
- * @title: MetaColorManager
- * @short_description: Interfaces for managing color-related properties like
- *   color look-up tables and color spaces.
+ * MetaColorManager:
+ * 
+ * Interfaces for managing color-related properties like
+ * color look-up tables and color spaces.
  *
  * Each MetaBackend has a MetaColorManager which includes interfaces for querying
  * and altering the color-related properties for displays associated with that
diff --git a/src/backends/meta-cursor-tracker.c b/src/backends/meta-cursor-tracker.c
index b0a5d14e4..8f91ef8e9 100644
--- a/src/backends/meta-cursor-tracker.c
+++ b/src/backends/meta-cursor-tracker.c
@@ -20,11 +20,10 @@
  */
 
 /**
- * SECTION:cursor-tracker
- * @title: MetaCursorTracker
- * @short_description: Mutter cursor tracking helper. Originally only
- *                     tracking the cursor image, now more of a "core
- *                     pointer abstraction"
+ * MetaCursorTracker:
+ * 
+ * Mutter cursor tracking helper. Originally only tracking
+ * the cursor image, now more of a "core pointer abstraction"
  */
 
 #include "config.h"
diff --git a/src/backends/meta-idle-monitor.c b/src/backends/meta-idle-monitor.c
index 879924de8..54c79bf7a 100644
--- a/src/backends/meta-idle-monitor.c
+++ b/src/backends/meta-idle-monitor.c
@@ -21,9 +21,9 @@
  */
 
 /**
- * SECTION:idle-monitor
- * @title: MetaIdleMonitor
- * @short_description: Mutter idle counter (similar to X's IDLETIME)
+ * MetaIdleMonitor:
+ * 
+ * Mutter idle counter (similar to X's IDLETIME)
  */
 
 #include "config.h"
diff --git a/src/backends/meta-input-settings.c b/src/backends/meta-input-settings.c
index b606006eb..9c2c674b3 100644
--- a/src/backends/meta-input-settings.c
+++ b/src/backends/meta-input-settings.c
@@ -20,9 +20,9 @@
  */
 
 /**
- * SECTION:input-settings
- * @title: MetaInputSettings
- * @short_description: Mutter input device configuration
+ * MetaInputSettings:
+ * 
+ * Mutter input device configuration
  */
 
 #include "config.h"
diff --git a/src/backends/meta-logical-monitor.c b/src/backends/meta-logical-monitor.c
index b562e5acb..5f15fa6b7 100644
--- a/src/backends/meta-logical-monitor.c
+++ b/src/backends/meta-logical-monitor.c
@@ -20,21 +20,21 @@
  */
 
 /**
- * SECTION:meta-logical-monitor
- * @title: MetaLogicalMonitor
- * @short_description: An abstraction for a monitor(set) and its configuration.
+ * MetaLogicalMonitor:
+ * 
+ * An abstraction for a monitor(set) and its configuration.
  *
  * A logical monitor is a group of one or more physical monitors that
  * must behave and be treated as single one. This happens, for example,
  * when 2 monitors are mirrored. Each physical monitor is represented
- * by a #MetaMonitor.
+ * by a [class@Meta.Monitor].
  *
  * #MetaLogicalMonitor has a single viewport, with its owns transformations
- * (such as scaling), that are applied to all the #MetaMonitor<!-- -->s that
+ * (such as scaling), that are applied to all the [class@Meta.Monitor]s that
  * are grouped by it.
  *
  * #MetaLogicalMonitor provides an abstraction that makes it easy to handle
- * the specifics of setting up different #MetaMonitor<!-- -->s. It then can
+ * the specifics of setting up different [class@Meta.Monitor]s. It then can
  * be used more easily by #MetaRendererView.
  */
 
diff --git a/src/backends/meta-monitor-manager.c b/src/backends/meta-monitor-manager.c
index bd02c55bb..46d816c7e 100644
--- a/src/backends/meta-monitor-manager.c
+++ b/src/backends/meta-monitor-manager.c
@@ -25,9 +25,9 @@
  */
 
 /**
- * SECTION:meta-monitor-manager
- * @title: MetaMonitorManager
- * @short_description: A manager for multiple monitors
+ * MetaMonitorManager:
+ * 
+ * A manager for multiple monitors
  *
  * #MetaMonitorManager is an abstract class which contains methods to handle
  * multiple monitors (both #MetaMonitor and #MetaLogicalMonitor) and GPU's
@@ -551,7 +551,7 @@ ensure_hdr_settings (MetaMonitorManager *manager)
  * @manager: A #MetaMonitorManager object
  *
  * Returns whether the monitor manager is headless, i.e. without
- * any #MetaLogicalMonitor<!-- -->s attached to it.
+ * any `MetaLogicalMonitor`s attached to it.
  *
  * Returns: %TRUE if no monitors are attached, %FALSE otherwise.
  */
@@ -3188,10 +3188,10 @@ initialize_dbus_interface (MetaMonitorManager *manager)
  * meta_monitor_manager_get_num_logical_monitors:
  * @manager: A #MetaMonitorManager object
  *
- * Returns the number of #MetaLogicalMonitor<!-- -->s (can be 0 in case of a
+ * Returns the number of `MetaLogicalMonitor`s (can be 0 in case of a
  * headless setup).
  *
- * Returns: the total number of #MetaLogicalMonitor<!-- -->s.
+ * Returns: the total number of `MetaLogicalMonitor`s.
  */
 int
 meta_monitor_manager_get_num_logical_monitors (MetaMonitorManager *manager)
@@ -3203,7 +3203,7 @@ meta_monitor_manager_get_num_logical_monitors (MetaMonitorManager *manager)
  * meta_monitor_manager_get_logical_monitors:
  * @manager: A #MetaMonitorManager object
  *
- * Returns the list of #MetaLogicalMonitor<!-- -->s that is handled. See also
+ * Returns the list of `MetaLogicalMonitor`s that is handled. See also
  * meta_monitor_manager_get_num_logical_monitors() if you only need the size of
  * the list.
  *
@@ -3421,11 +3421,11 @@ meta_monitor_manager_get_logical_monitor_neighbor (MetaMonitorManager  *manager,
  * meta_monitor_manager_get_monitors:
  * @manager: A #MetaMonitorManager object
  *
- * Returns the list of #MetaMonitor<!-- -->s. See also
+ * Returns the list of [class@Meta.Monitor]s. See also
  * meta_monitor_manager_get_logical_monitors() for a list of
- * #MetaLogicalMonitor<!-- -->s.
+ * `MetaLogicalMonitor`s.
  *
- * Returns: (transfer none) (nullable): the list of #MetaMonitor<!-- -->s.
+ * Returns: (transfer none) (nullable): the list of [class@Meta.Monitor]s.
  */
 GList *
 meta_monitor_manager_get_monitors (MetaMonitorManager *manager)
diff --git a/src/backends/meta-pointer-constraint.c b/src/backends/meta-pointer-constraint.c
index 0bc57a4c4..328951c99 100644
--- a/src/backends/meta-pointer-constraint.c
+++ b/src/backends/meta-pointer-constraint.c
@@ -23,9 +23,9 @@
  */
 
 /**
- * SECTION:meta-pointer-constraint
- * @title: MetaPointerConstraint
- * @short_description: Pointer client constraints.
+ * MetaPointerConstraint:
+ * 
+ * Pointer client constraints.
  *
  * A MetaPointerConstraint can be used to implement any kind of pointer
  * constraint as requested by a client, such as cursor lock.
diff --git a/src/backends/meta-renderer-view.c b/src/backends/meta-renderer-view.c
index b974fcbde..25c0f9cae 100644
--- a/src/backends/meta-renderer-view.c
+++ b/src/backends/meta-renderer-view.c
@@ -16,9 +16,9 @@
  */
 
 /**
- * SECTION:meta-renderer-view
- * @title: MetaRendererView
- * @short_description: Renders (a part of) the global stage.
+ * MetaRendererView:
+ * 
+ * Renders (a part of) the global stage.
  *
  * A MetaRendererView object is responsible for rendering (a part of) the
  * global stage, or more precisely: the part that matches what can be seen on a
diff --git a/src/backends/meta-renderer.c b/src/backends/meta-renderer.c
index f380a9987..575bd950c 100644
--- a/src/backends/meta-renderer.c
+++ b/src/backends/meta-renderer.c
@@ -23,13 +23,13 @@
  */
 
 /**
- * SECTION:meta-renderer
- * @title: MetaRenderer
- * @short_description: Keeps track of the different renderer views.
+ * MetaRenderer:
+ * 
+ * Keeps track of the different renderer views.
  *
  * A MetaRenderer object has 2 functions:
  *
- * 1) Keeping a list of #MetaRendererView<!-- -->s, each responsible for
+ * 1) Keeping a list of `MetaRendererView`s, each responsible for
  * rendering a part of the stage, corresponding to each #MetaLogicalMonitor. It
  * keeps track of this list by querying the list of logical monitors in the
  * #MetaBackend's #MetaMonitorManager, and creating a renderer view for each
diff --git a/src/backends/native/meta-backend-native.c b/src/backends/native/meta-backend-native.c
index 5c1690d88..97650ee28 100644
--- a/src/backends/native/meta-backend-native.c
+++ b/src/backends/native/meta-backend-native.c
@@ -23,9 +23,9 @@
  */
 
 /**
- * SECTION:meta-backend-native
- * @title: MetaBackendNative
- * @short_description: A native (KMS/evdev) MetaBackend
+ * MetaBackendNative:
+ * 
+ * A native (KMS/evdev) MetaBackend
  *
  * MetaBackendNative is an implementation of #MetaBackend that uses "native"
  * technologies like DRM/KMS and libinput/evdev to perform the necessary
diff --git a/src/backends/native/meta-barrier-native.c b/src/backends/native/meta-barrier-native.c
index f93bcecd9..be3a912db 100644
--- a/src/backends/native/meta-barrier-native.c
+++ b/src/backends/native/meta-barrier-native.c
@@ -23,9 +23,9 @@
  */
 
 /**
- * SECTION:barrier-native
- * @Title: MetaBarrierImplNative
- * @Short_Description: Pointer barriers implementation for the native backend
+ * MetaBarrierImplNative:
+ * 
+ * Pointer barriers implementation for the native backend
  */
 
 #include "config.h"
diff --git a/src/backends/native/meta-clutter-backend-native.c b/src/backends/native/meta-clutter-backend-native.c
index 97affc7b8..43f2f1116 100644
--- a/src/backends/native/meta-clutter-backend-native.c
+++ b/src/backends/native/meta-clutter-backend-native.c
@@ -23,9 +23,9 @@
  */
 
 /**
- * SECTION:meta-clutter-backend-native
- * @title: MetaClutterBackendNatve
- * @short_description: A native backend which renders using EGL.
+ * MetaClutterBackendNative:
+ * 
+ * A native backend which renders using EGL.
  *
  * MetaClutterBackendNative is the #ClutterBackend which is used by the native
  * (as opposed to the X) backend. It creates a stage with #MetaStageNative and
diff --git a/src/backends/native/meta-monitor-manager-native.c b/src/backends/native/meta-monitor-manager-native.c
index 589326a8b..3ec8981b6 100644
--- a/src/backends/native/meta-monitor-manager-native.c
+++ b/src/backends/native/meta-monitor-manager-native.c
@@ -23,9 +23,9 @@
  */
 
 /**
- * SECTION:meta-monitor-manager-native
- * @title: MetaMonitorManagerNative
- * @short_description: A subclass of #MetaMonitorManager using Linux DRM
+ * MetaMonitorManagerNative:
+ * 
+ * A subclass of #MetaMonitorManager using Linux DRM
  *
  * #MetaMonitorManagerNative is a subclass of #MetaMonitorManager which
  * implements its functionality "natively": it uses the appropriate
diff --git a/src/backends/x11/meta-backend-x11.c b/src/backends/x11/meta-backend-x11.c
index 0f7fe08a7..a98cffd2b 100644
--- a/src/backends/x11/meta-backend-x11.c
+++ b/src/backends/x11/meta-backend-x11.c
@@ -23,9 +23,9 @@
  */
 
 /**
- * SECTION:meta-backend-x11
- * @title: MetaBackendX11
- * @short_description: A X11 MetaBackend
+ * MetaBackendX11:
+ * 
+ * A X11 MetaBackend
  *
  * MetaBackendX11 is an implementation of #MetaBackend using X and X
  * extensions, like XInput and XKB.
diff --git a/src/backends/x11/meta-barrier-x11.c b/src/backends/x11/meta-barrier-x11.c
index e63c3096b..b5c38ba79 100644
--- a/src/backends/x11/meta-barrier-x11.c
+++ b/src/backends/x11/meta-barrier-x11.c
@@ -24,9 +24,9 @@
  */
 
 /**
- * SECTION:barrier-x11
- * @Title: MetaBarrierImplX11
- * @Short_Description: Pointer barriers implementation for X11
+ * MetaBarrierImplX11:
+ * 
+ * Pointer barriers implementation for X11
  */
 
 #include "config.h"
diff --git a/src/backends/x11/meta-monitor-manager-xrandr.c b/src/backends/x11/meta-monitor-manager-xrandr.c
index beb9fb80d..d1483c556 100644
--- a/src/backends/x11/meta-monitor-manager-xrandr.c
+++ b/src/backends/x11/meta-monitor-manager-xrandr.c
@@ -25,9 +25,9 @@
  */
 
 /**
- * SECTION:meta-monitor-manager-xrandr
- * @title: MetaMonitorManagerXrandr
- * @short_description: A subclass of #MetaMonitorManager using XRadR
+ * MetaMonitorManagerXrandr:
+ * 
+ * A subclass of #MetaMonitorManager using XRadR
  *
  * #MetaMonitorManagerXrandr is a subclass of #MetaMonitorManager which
  * implements its functionality using the RandR X protocol.
diff --git a/src/compositor/compositor.c b/src/compositor/compositor.c
index fd1a75a88..9c998851f 100644
--- a/src/compositor/compositor.c
+++ b/src/compositor/compositor.c
@@ -1,9 +1,9 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
 /**
- * SECTION:compositor
- * @Title: MetaCompositor
- * @Short_Description: Compositor API
+ * MetaCompositor:
+ * 
+ * Compositor API
  *
  * At a high-level, a window is not-visible or visible. When a
  * window is added (with meta_compositor_add_window()) it is not visible.
diff --git a/src/compositor/meta-background-content.c b/src/compositor/meta-background-content.c
index f5f635f4c..bb7b01968 100644
--- a/src/compositor/meta-background-content.c
+++ b/src/compositor/meta-background-content.c
@@ -21,13 +21,13 @@
 
 
 /**
- * SECTION:meta-background-content
- * @title: MetaBackgroundContent
- * @short_description: ClutterContent for painting the root window background
+ * MetaBackgroundContent:
  *
- */
-
-/*
+ * This class handles tracking and painting the root window background.
+ * 
+ * By integrating with [class@Meta.WindowGroup] we can avoid painting parts of
+ * the background that are obscured by other windows.
+ * 
  * The overall model drawing model of this content is that we have one
  * texture, or two interpolated textures, possibly with alpha or
  * margins that let the underlying background show through, blended
diff --git a/src/compositor/meta-background-group.c b/src/compositor/meta-background-group.c
index e30b8af4c..2a90742c4 100644
--- a/src/compositor/meta-background-group.c
+++ b/src/compositor/meta-background-group.c
@@ -1,9 +1,9 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
 /**
- * SECTION:meta-background-group
- * @title: MetaBackgroundGroup
- * @short_description: Container for background actors
+ * MetaBackgroundGroup:
+ * 
+ * Container for background actors
  *
  * This class is a subclass of ClutterActor with special handling for
  * MetaBackgroundActor/MetaBackgroundGroup when painting children.
diff --git a/src/compositor/meta-background-image.c b/src/compositor/meta-background-image.c
index 1e756bd2a..2aed9139f 100644
--- a/src/compositor/meta-background-image.c
+++ b/src/compositor/meta-background-image.c
@@ -16,12 +16,6 @@
  * along with this program; if not, see <http://www.gnu.org/licenses/>.
  */
 
-/**
- * SECTION:meta-background-image
- * @title: MetaBackgroundImage
- * @short_description: objects holding images loaded from files, used for backgrounds
- */
-
 #include "config.h"
 
 #include "meta/meta-background-image.h"
@@ -43,9 +37,10 @@ static guint signals[LAST_SIGNAL] = { 0 };
 /**
  * MetaBackgroundImageCache:
  *
- * #MetaBackgroundImageCache caches loading of textures for backgrounds; there's actually
- * nothing background specific about it, other than it is tuned to work well for
- * large images as typically are used for backgrounds.
+ * Caches loading of textures for backgrounds.
+ * 
+ * There's actually nothing background specific about it, other than it is tuned
+ * to work well for large images as typically are used for backgrounds.
  */
 struct _MetaBackgroundImageCache
 {
@@ -57,7 +52,7 @@ struct _MetaBackgroundImageCache
 /**
  * MetaBackgroundImage:
  *
- * #MetaBackgroundImage is an object that represents a loaded or loading background image.
+ * Represents a loaded or loading background image.
  */
 struct _MetaBackgroundImage
 {
@@ -220,10 +215,11 @@ out:
  * @file: #GFile to load
  *
  * Loads an image to use as a background, or returns a reference to an
- * image that is already in the process of loading or loaded. In either
- * case, what is returned is a #MetaBackgroundImage which can be dereferenced
- * to get a #CoglTexture. If meta_background_image_is_loaded() returns %TRUE,
- * the background is loaded, otherwise the MetaBackgroundImage::loaded
+ * image that is already in the process of loading or loaded.
+ * 
+ * In either case, what is returned is a [class@Meta.BackgroundImage] which can be dereferenced
+ * to get a [iface@Cogl.Texture]. If [method@Meta.BackgroundImage.is_loaded] returns %TRUE,
+ * the background is loaded, otherwise the [signal@Meta.BackgroundImage::loaded]
  * signal will be emitted exactly once. The 'loaded' state means that the
  * loading process finished, whether it succeeded or failed.
  *
diff --git a/src/compositor/meta-cullable.c b/src/compositor/meta-cullable.c
index e306c56e2..4f070ffcf 100644
--- a/src/compositor/meta-cullable.c
+++ b/src/compositor/meta-cullable.c
@@ -45,9 +45,9 @@ has_active_effects (ClutterActor *actor)
 }
 
 /**
- * SECTION:meta-cullable
- * @title: MetaCullable
- * @short_description: CPU culling operations for efficient drawing
+ * MetaCullable:
+ * 
+ * CPU culling operations for efficient drawing
  *
  * When we are painting a stack of 5-10 large actors, the standard
  * bottom-to-top method of drawing every actor results in a tremendous
diff --git a/src/compositor/meta-dnd-actor.c b/src/compositor/meta-dnd-actor.c
index eefe43a3e..b775d5a38 100644
--- a/src/compositor/meta-dnd-actor.c
+++ b/src/compositor/meta-dnd-actor.c
@@ -19,9 +19,9 @@
  */
 
 /**
- * SECTION:meta-dnd-actor
- * @title: MetaDnDActor
- * @short_description: Actor for painting the drag and drop surface
+ * MetaDnDActor:
+ * 
+ * Actor for painting the drag and drop surface
  *
  */
 
diff --git a/src/compositor/meta-feedback-actor.c b/src/compositor/meta-feedback-actor.c
index 8a933e37a..0cfde6a13 100644
--- a/src/compositor/meta-feedback-actor.c
+++ b/src/compositor/meta-feedback-actor.c
@@ -19,9 +19,9 @@
  */
 
 /**
- * SECTION:meta-feedback-actor
- * @title: MetaFeedbackActor
- * @short_description: Actor for painting user interaction feedback
+ * MetaFeedbackActor:
+ * 
+ * Actor for painting user interaction feedback
  */
 
 #include "config.h"
diff --git a/src/compositor/meta-plugin.c b/src/compositor/meta-plugin.c
index 8fdd691a3..9dded9671 100644
--- a/src/compositor/meta-plugin.c
+++ b/src/compositor/meta-plugin.c
@@ -20,10 +20,9 @@
  */
 
 /**
- * SECTION:meta-plugin
- * @title: MetaPlugin
- * @short_description: Entry point for plugins
- *
+ * MetaPlugin:
+ * 
+ * Entry point for plugins
  */
 
 #include "config.h"
diff --git a/src/compositor/meta-shadow-factory.c b/src/compositor/meta-shadow-factory.c
index d6424d3be..2644331e6 100644
--- a/src/compositor/meta-shadow-factory.c
+++ b/src/compositor/meta-shadow-factory.c
@@ -16,12 +16,6 @@
  * along with this program; if not, see <http://www.gnu.org/licenses/>.
  */
 
-/**
- * SECTION:meta-shadow-factory
- * @title: MetaShadowFactory
- * @short_description: Create and cache shadow textures for arbitrary window shapes
- */
-
 #include "config.h"
 
 #include <math.h>
@@ -193,9 +187,10 @@ meta_shadow_unref (MetaShadow *shadow)
  *   drawing.
  *
  * Paints the shadow at the given position, for the specified actual
- * size of the region. (Since a #MetaShadow can be shared between
- * different sizes with the same extracted #MetaWindowShape the
- * size needs to be passed in here.)
+ * size of the region. 
+ * 
+ * Since a #MetaShadow can be shared between different sizes with 
+ * the same extracted [struct@Meta.WindowShape] the size needs to be passed in here.
  */
 void
 meta_shadow_paint (MetaShadow      *shadow,
diff --git a/src/compositor/meta-shaped-texture.c b/src/compositor/meta-shaped-texture.c
index 6a37111af..e05e79cd7 100644
--- a/src/compositor/meta-shaped-texture.c
+++ b/src/compositor/meta-shaped-texture.c
@@ -22,9 +22,9 @@
  */
 
 /**
- * SECTION:meta-shaped-texture
- * @title: MetaShapedTexture
- * @short_description: A ClutterContent which draws a shaped texture
+ * MetaShapedTexture:
+ * 
+ * A ClutterContent which draws a shaped texture
  *
  * A MetaShapedTexture draws a #CoglTexture (often provided from a client
  * surface) in such a way that it matches any required transformations that
diff --git a/src/compositor/meta-surface-actor.c b/src/compositor/meta-surface-actor.c
index 1bc58667a..06af6a0a8 100644
--- a/src/compositor/meta-surface-actor.c
+++ b/src/compositor/meta-surface-actor.c
@@ -1,9 +1,9 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
 /**
- * SECTION:meta-surface-actor
- * @title: MetaSurfaceActor
- * @short_description: An actor representing a surface in the scene graph
+ * MetaSurfaceActor:
+ * 
+ * An actor representing a surface in the scene graph
  *
  * MetaSurfaceActor is an abstract class which represents a surface in the
  * Clutter scene graph. A subclass can implement the specifics of a surface
diff --git a/src/compositor/meta-texture-mipmap.h b/src/compositor/meta-texture-mipmap.h
index fd83a49c2..79e0a8121 100644
--- a/src/compositor/meta-texture-mipmap.h
+++ b/src/compositor/meta-texture-mipmap.h
@@ -28,8 +28,9 @@
 G_BEGIN_DECLS
 
 /**
- * SECTION:MetaTextureMipmap
- * @short_description: mipmap handling for textures
+ * MetaTextureMipmap:
+ * 
+ * Mipmap handling for textures
  *
  * A #MetaTextureMipmap is used to get GL mipmaps for a texture
  */
diff --git a/src/compositor/meta-window-actor.c b/src/compositor/meta-window-actor.c
index 48d4d02d0..b9c049800 100644
--- a/src/compositor/meta-window-actor.c
+++ b/src/compositor/meta-window-actor.c
@@ -1,10 +1,9 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
 /**
- * SECTION:meta-window-actor
- * @title: MetaWindowActor
- * @short_description: An actor representing a top-level window in the scene
- *   graph
+ * MetaWindowActor:
+ * 
+ * An actor representing a top-level window in the scene graph
  *
  * #MetaWindowActor is a #ClutterActor that adds a notion of a window to the
  * Clutter scene graph. It contains a #MetaWindow which provides the windowing
diff --git a/src/core/bell.c b/src/core/bell.c
index f0c6f9463..7b302d612 100644
--- a/src/core/bell.c
+++ b/src/core/bell.c
@@ -21,8 +21,9 @@
  */
 
 /*
- * SECTION:bell
- * @short_description: Ring the bell or flash the screen
+ * bell:
+ * 
+ * Ring the bell or flash the screen
  *
  * Sometimes, X programs "ring the bell", whatever that means. Mutter lets
  * the user configure the bell to be audible or visible (aka visual), and
diff --git a/src/core/boxes.c b/src/core/boxes.c
index 315844a88..d2143144c 100644
--- a/src/core/boxes.c
+++ b/src/core/boxes.c
@@ -1,11 +1,5 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
-/**
- * SECTION:boxes
- * @Title: MetaRectangle
- * @Short_Description: Simple box operations
- */
-
 /*
  * Copyright (C) 2005, 2006 Elijah Newren
  * [meta_rectangle_intersect() is copyright the GTK+ Team according to Havoc,
diff --git a/src/core/display.c b/src/core/display.c
index e74cacef0..30823c7ff 100644
--- a/src/core/display.c
+++ b/src/core/display.c
@@ -21,9 +21,9 @@
  */
 
 /**
- * SECTION:display
- * @title: MetaDisplay
- * @short_description: Mutter display representation
+ * MetaDisplay:
+ * 
+ * Mutter display representation
  *
  * The display is represented as a #MetaDisplay struct.
  */
@@ -386,12 +386,13 @@ meta_display_class_init (MetaDisplayClass *klass)
    * @message: (allow-none): The message to display, or %NULL
    *  to clear a previous restart message.
    *
-   * The ::show-restart-message signal will be emitted to indicate
-   * that the compositor should show a message during restart. This is
-   * emitted when meta_restart() is called, either by Mutter
-   * internally or by the embedding compositor.  The message should be
+   * The signal will be emitted to indicate that the compositor 
+   * should show a message during restart.
+   * 
+   * This is emitted when [func@Meta.restart] is called, either by Mutter
+   * internally or by the embedding compositor. The message should be
    * immediately added to the Clutter stage in its final form -
-   * ::restart will be emitted to exit the application and leave the
+   * [signal@Meta.Display::restart] will be emitted to exit the application and leave the
    * stage contents frozen as soon as the the stage is painted again.
    *
    * On case of failure to restart, this signal will be emitted again
@@ -414,11 +415,13 @@ meta_display_class_init (MetaDisplayClass *klass)
    * MetaDisplay::restart:
    * @display: the #MetaDisplay instance
    *
-   * The ::restart signal is emitted to indicate that compositor
-   * should reexec the process. This is
-   * emitted when meta_restart() is called, either by Mutter
-   * internally or by the embedding compositor. See also
-   * ::show-restart-message.
+   * The signal is emitted to indicate that compositor
+   * should reexec the process.
+   * 
+   * This is emitted when [func@Meta.restart] is called,
+   * either by Mutter internally or by the embedding compositor.
+   * 
+   * See also [signal@Meta.Display::show-restart-message].
    *
    * Returns: %FALSE to indicate that the compositor could not
    *  be restarted. When the compositor is restarted, the signal
diff --git a/src/core/keybindings.c b/src/core/keybindings.c
index 63c7315ce..e78ff19f4 100644
--- a/src/core/keybindings.c
+++ b/src/core/keybindings.c
@@ -22,9 +22,9 @@
  */
 
 /**
- * SECTION:keybindings
- * @Title: MetaKeybinding
- * @Short_Description: Key bindings
+ * MetaKeybinding:
+ * 
+ * Key bindings
  */
 
 #include "config.h"
diff --git a/src/core/meta-gesture-tracker.c b/src/core/meta-gesture-tracker.c
index f05c09000..ff3219a5d 100644
--- a/src/core/meta-gesture-tracker.c
+++ b/src/core/meta-gesture-tracker.c
@@ -20,9 +20,9 @@
  */
 
 /**
- * SECTION:gesture-tracker
- * @Title: MetaGestureTracker
- * @Short_Description: Manages gestures on windows/desktop
+ * MetaGestureTracker:
+ * 
+ * Manages gestures on windows/desktop
  *
  * Forwards touch events to clutter actors, and accepts/rejects touch sequences
  * based on the outcome of those.
diff --git a/src/core/prefs.c b/src/core/prefs.c
index 25a1524af..b207030f9 100644
--- a/src/core/prefs.c
+++ b/src/core/prefs.c
@@ -21,9 +21,9 @@
  */
 
 /**
- * SECTION:prefs
- * @title: Preferences
- * @short_description: Mutter preferences
+ * Preferences:
+ * 
+ * Mutter preferences
  */
 
 #include "config.h"
diff --git a/src/core/restart-helper.c b/src/core/restart-helper.c
index 68ede2671..24664a9c9 100644
--- a/src/core/restart-helper.c
+++ b/src/core/restart-helper.c
@@ -1,8 +1,9 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
 /*
- * SECTION:restart-helper
- * @short_description: helper program during a restart
+ * restart-helper
+ * 
+ * Helper program during a restart
  *
  * To smoothly restart Mutter, we want to keep the composite
  * overlay window enabled during the restart. This is done by
diff --git a/src/core/restart.c b/src/core/restart.c
index cd8ba6872..c79eed050 100644
--- a/src/core/restart.c
+++ b/src/core/restart.c
@@ -18,8 +18,9 @@
  */
 
 /*
- * SECTION:restart
- * @short_description: Smoothly restart the compositor
+ * restart:
+ *
+ * Smoothly restart the compositor
  *
  * There are some cases where we need to restart Mutter in order
  * to deal with changes in state - the particular case inspiring
@@ -117,13 +118,18 @@ child_setup (gpointer user_data)
  * @message: (allow-none): message to display to the user, or %NULL
  * @context: a #MetaContext
  *
- * Starts the process of restarting the compositor. Note that Mutter's
- * involvement here is to make the restart visually smooth for the
- * user - it cannot itself safely reexec a program that embeds libmuttter.
+ * Starts the process of restarting the compositor.
+ * 
+ * Note that Mutter's involvement here is to make the restart
+ * visually smooth for the user - it cannot itself safely 
+ * reexec a program that embeds libmuttter.
+ * 
  * So in order for this to work, the compositor must handle two
- * signals -  MetaDisplay::show-restart-message, to display the
- * message passed here on the Clutter stage, and ::restart to actually
- * reexec the compositor.
+ * signals 
+ * 
+ * - [signal@Meta.Display::show-restart-message], to display the
+ * message passed here on the Clutter stage
+ * - [signal@Meta.Display::restart] to actually reexec the compositor.
  */
 void
 meta_restart (const char  *message,
@@ -202,7 +208,8 @@ meta_restart (const char  *message,
  *
  * Returns %TRUE if this instance of Mutter comes from Mutter
  * restarting itself (for example to enable/disable stereo.)
- * See meta_restart(). If this is the case, any startup visuals
+ * 
+ * See [func@Meta.restart]. If this is the case, any startup visuals
  * or animations should be suppressed.
  */
 gboolean
diff --git a/src/core/stack-tracker.c b/src/core/stack-tracker.c
index 8292b7b91..d55206427 100644
--- a/src/core/stack-tracker.c
+++ b/src/core/stack-tracker.c
@@ -1,8 +1,9 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
 /*
- * SECTION:stack-tracker
- * @short_description: Track stacking order for compositor
+ * stack-tracker:
+ *
+ * Track stacking order for compositor
  *
  * #MetaStackTracker maintains the most accurate view we have at a
  * given point of time of the ordering of the children of the root
diff --git a/src/core/stack.c b/src/core/stack.c
index 2481adf78..a91dca18d 100644
--- a/src/core/stack.c
+++ b/src/core/stack.c
@@ -1,8 +1,9 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
 /*
- * SECTION:stack
- * @short_description: Which windows cover which other windows
+ * stack:
+ *
+ * Which windows cover which other windows
  */
 
 /*
diff --git a/src/core/stack.h b/src/core/stack.h
index a33fac45f..82a8f34dd 100644
--- a/src/core/stack.h
+++ b/src/core/stack.h
@@ -22,8 +22,9 @@
 #define META_STACK_H
 
 /**
- * SECTION:stack
- * @short_description: Which windows cover which other windows
+ * stack:
+ * 
+ * Which windows cover which other windows
  *
  * There are two factors that determine window position.
  *
diff --git a/src/core/util.c b/src/core/util.c
index 79adb11bb..7f44f74a6 100644
--- a/src/core/util.c
+++ b/src/core/util.c
@@ -16,11 +16,6 @@
  * along with this program; if not, see <http://www.gnu.org/licenses/>.
  */
 
-/**
- * SECTION:util
- * @title: Utility functions
- * @short_description: Miscellaneous utility functions
- */
 
 #define _POSIX_C_SOURCE 200112L /* for fdopen() */
 
@@ -175,10 +170,11 @@ meta_add_verbose_topic (MetaDebugTopic topic)
  * meta_remove_verbose_topic:
  * @topic: Topic for which logging will be stopped
  *
- * Stop printing log messages for the given topic @topic.  Note
- * that this method does not stack with meta_add_verbose_topic();
- * i.e. if two calls to meta_add_verbose_topic() for the same
- * topic are made, one call to meta_remove_verbose_topic() will
+ * Stop printing log messages for the given topic @topic.
+ * 
+ * Note that this method does not stack with [func@Meta.add_verbose_topic];
+ * i.e. if two calls to [func@Meta.add_verbose_topic] for the same
+ * topic are made, one call to [func@Meta.remove_verbose_topic]  will
  * remove it.
  */
 void
diff --git a/src/core/window.c b/src/core/window.c
index 40cc7b7da..4afa76286 100644
--- a/src/core/window.c
+++ b/src/core/window.c
@@ -21,39 +21,40 @@
  */
 
 /**
- * SECTION:meta-window
- * @title: MetaWindow
- * @short_description: A display-agnostic abstraction for a window.
+ * MetaWindow:
+ * 
+ * A display-agnostic abstraction for a window.
  *
  * #MetaWindow is the core abstraction in Mutter of a window. It has the
  * properties you'd expect, such as a title, whether it's fullscreen,
  * has decorations, etc.
  *
  * Since a lot of different kinds of windows exist, each window also a
- * #MetaWindowType which denotes which kind of window we're exactly dealing
+ * [enum@Meta.WindowType] which denotes which kind of window we're exactly dealing
  * with. For example, one expects slightly different behaviour from a dialog
  * than a "normal" window. The type of a window can be queried with
- * meta_window_get_type().
+ * [method@Meta.Window.get_window_type].
  *
  * Common API for windows include:
- * - Minimizing: meta_window_minimize() / meta_window_unminimize()
- * - Maximizing: meta_window_maximize() / meta_window_unmaximize()
- * - Fullscreen: meta_window_make_fullscreen() / meta_window_unmake_fullscreen()
- *               / meta_window_is_fullscreen()
+ * 
+ * - Minimizing: [method@Meta.Window.minimize] / [method@Meta.Window.unminimize]
+ * - Maximizing: [method@Meta.Window.maximize] / [method@Meta.Window.unmaximize]
+ * - Fullscreen: [method@Meta.Window.make_fullscreen] / [method@Meta.Window.unmake_fullscreen]
+ *               / [method@Meta.Window.is_fullscreen]
  *
- * Each #MetaWindow is part of either one or all #MetaWorkspace<!-- -->s of the
+ * Each #MetaWindow is part of either one or all [class@Meta.Workspace]s of the
  * desktop. You can activate a window on a certain workspace using
- * meta_window_activate_with_workspace(), and query on which workspace it is
- * located using meta_window_located_on_workspace(). The workspace it is part
- * of can be obtained using meta_window_get_workspace().
+ * [method@Meta.Window.activate_with_workspace], and query on which workspace it is
+ * located using [method@Meta.Window.located_on_workspace]. The workspace it is part
+ * of can be obtained using [method@Meta.Window.get_workspace].
  *
  * Each display protocol should make a subclass to be compatible with that
  * protocols' specifics, for example #MetaWindowX11 and #MetaWindowWayland.
  * This is independent of the protocol that the client uses, which is modeled
- * using the #MetaWindowClientType enum.
+ * using the [enum@Meta.WindowClientType] enum.
  *
  * To integrate within the Clutter scene graph, which deals with the actual
- * rendering, each #MetaWindow will be part of a #MetaWindowActor.
+ * rendering, each #MetaWindow will be part of a [class@Meta.WindowActor].
  */
 
 #include "config.h"
@@ -713,9 +714,11 @@ meta_window_class_init (MetaWindowClass *klass)
    * @window: a #MetaWindow
    *
    * This is emitted when the position of a window might
-   * have changed. Specifically, this is emitted when the
-   * position of the toplevel window has changed, or when
-   * the position of the client window has changed.
+   * have changed.
+   * 
+   * Specifically, this is emitted when the position of
+   * the toplevel window has changed, or when the position
+   * of the client window has changed.
    */
   window_signals[POSITION_CHANGED] =
     g_signal_new ("position-changed",
@@ -744,8 +747,10 @@ meta_window_class_init (MetaWindowClass *klass)
    * @window: a #MetaWindow
    *
    * This is emitted when the size of a window might
-   * have changed. Specifically, this is emitted when the
-   * size of the toplevel window has changed, or when the
+   * have changed.
+   * 
+   * Specifically, this is emitted when the size of
+   * the toplevel window has changed, or when the
    * size of the client window has changed.
    */
   window_signals[SIZE_CHANGED] =
@@ -3922,6 +3927,7 @@ meta_window_move_resize_internal (MetaWindow          *window,
  * Moves the window to the desired location on window's assigned
  * workspace, using the northwest edge of the frame as the reference,
  * instead of the actual window's origin, but only if a frame is present.
+ * 
  * Otherwise, acts identically to meta_window_move().
  */
 void
@@ -4374,9 +4380,10 @@ meta_window_frame_rect_to_client_rect (MetaWindow    *window,
  * @rect: (out): pointer to an allocated #MetaRectangle
  *
  * Gets the rectangle that bounds @window that is what the user thinks of
- * as the edge of the window. This doesn't include any extra reactive
- * area that we or the client adds to the window, or any area that the
- * client adds to draw a client-side shadow.
+ * as the edge of the window.
+ * 
+ * This doesn't include any extra reactive area that we or the client
+ * adds to the window, or any area that the client adds to draw a client-side shadow.
  */
 void
 meta_window_get_frame_rect (const MetaWindow *window,
@@ -5235,9 +5242,10 @@ meta_window_set_focused_internal (MetaWindow *window,
  * @window: a #MetaWindow
  * @rect: (out): rectangle into which to store the returned geometry.
  *
- * Gets the location of the icon corresponding to the window. The location
- * will be provided set by the task bar or other user interface element
- * displaying the icon, and is relative to the root window.
+ * Gets the location of the icon corresponding to the window.
+ * 
+ * The location will be provided set by the task bar or other user interface
+ * element displaying the icon, and is relative to the root window.
  *
  * Return value: %TRUE if the icon geometry was successfully retrieved.
  */
@@ -5263,8 +5271,9 @@ meta_window_get_icon_geometry (MetaWindow    *window,
  * @window: a #MetaWindow
  * @rect: (nullable): rectangle with the desired geometry or %NULL.
  *
- * Sets or unsets the location of the icon corresponding to the window. If
- * set, the location should correspond to a dock, task bar or other user
+ * Sets or unsets the location of the icon corresponding to the window.
+ * 
+ * If set, the location should correspond to a dock, task bar or other user
  * interface element displaying the icon, and is relative to the root window.
  */
 void
@@ -5906,7 +5915,8 @@ meta_window_same_application (MetaWindow *window,
  * meta_window_is_client_decorated:
  *
  * Check if if the window has decorations drawn by the client.
- * (window->decorated refers only to whether we should add decorations)
+ * 
+ * `window->decorated` refers only to whether we should add decorations.
  */
 gboolean
 meta_window_is_client_decorated (MetaWindow *window)
@@ -6191,8 +6201,9 @@ meta_window_stack_just_above (MetaWindow *window,
  * @window: a #MetaWindow
  *
  * The user time represents a timestamp for the last time the user
- * interacted with this window.  Note this property is only available
- * for non-override-redirect windows.
+ * interacted with this window.
+ * 
+ * Note this property is only available for non-override-redirect windows.
  *
  * The property is set by Mutter initially upon window creation,
  * and updated thereafter on input events (key and button presses) seen by Mutter,
@@ -6370,8 +6381,9 @@ meta_window_get_frame (MetaWindow *window)
  * meta_window_appears_focused:
  * @window: a #MetaWindow
  *
- * Determines if the window should be drawn with a focused appearance. This is
- * true for focused windows but also true for windows with a focused modal
+ * Determines if the window should be drawn with a focused appearance.
+ * 
+ * This is true for focused windows but also true for windows with a focused modal
  * dialog attached.
  *
  * Return value: %TRUE if the window should be drawn with a focused frame
@@ -6451,7 +6463,8 @@ meta_window_get_window_type (MetaWindow *window)
  * meta_window_get_workspace:
  * @window: a #MetaWindow
  *
- * Gets the #MetaWorkspace that the window is currently displayed on.
+ * Gets the [class@Meta.Workspace] that the window is currently displayed on.
+ * 
  * If the window is on all workspaces, returns the currently active
  * workspace.
  *
@@ -6493,9 +6506,9 @@ meta_window_get_description (MetaWindow *window)
  * meta_window_get_wm_class:
  * @window: a #MetaWindow
  *
- * Return the current value of the name part of WM_CLASS X property.
+ * Return the current value of the name part of `WM_CLASS` X property.
  *
- * Returns: (nullable): the current value of the name part of WM_CLASS X
+ * Returns: (nullable): the current value of the name part of `WM_CLASS` X
  * property
  */
 const char *
@@ -6511,9 +6524,9 @@ meta_window_get_wm_class (MetaWindow *window)
  * meta_window_get_wm_class_instance:
  * @window: a #MetaWindow
  *
- * Return the current value of the instance part of WM_CLASS X property.
+ * Return the current value of the instance part of `WM_CLASS` X property.
  *
- * Returns: (nullable): the current value of the instance part of WM_CLASS X
+ * Returns: (nullable): the current value of the instance part of `WM_CLASS` X
  * property.
  */
 const char *
@@ -6954,8 +6967,9 @@ meta_window_get_frame_bounds (MetaWindow *window)
  * @window: a #MetaWindow
  *
  * Tests if @window should be attached to its parent window.
- * (If the "attach_modal_dialogs" option is not enabled, this will
- * always return %FALSE.)
+ * 
+ * If the `attach_modal_dialogs` option is not enabled, this will
+ * always return %FALSE.
  *
  * Return value: whether @window should be attached to its parent
  */
@@ -6985,8 +6999,9 @@ has_attached_foreach_func (MetaWindow *window,
  * @window: a #MetaWindow
  *
  * Tests if @window has any transients attached to it.
- * (If the "attach_modal_dialogs" option is not enabled, this will
- * always return %FALSE.)
+ * 
+ * If the `attach_modal_dialogs` option is not enabled, this will
+ * always return %FALSE.
  *
  * Return value: whether @window has attached transients
  */
diff --git a/src/core/workspace.c b/src/core/workspace.c
index a70791b46..8f0a66d2f 100644
--- a/src/core/workspace.c
+++ b/src/core/workspace.c
@@ -20,9 +20,9 @@
  */
 
 /**
- * SECTION:workspace
- * @title:MetaWorkspace
- * @short_description:Workspaces
+ * MetaWorkspace:
+ * 
+ * Workspaces
  *
  * A workspace is a set of windows which all live on the same
  * screen.  (You may also see the name "desktop" around the place,
diff --git a/src/meta/common.h b/src/meta/common.h
index 65d7a9808..e7163e3f6 100644
--- a/src/meta/common.h
+++ b/src/meta/common.h
@@ -34,9 +34,9 @@
 #include "meta/meta-enums.h"
 
 /**
- * SECTION:common
- * @Title: Common
- * @Short_Description: Mutter common types
+ * Common:
+ * 
+ * Mutter common types
  */
 
 /* This is set in stone and also hard-coded in GDK. */
diff --git a/src/meta/meta-background-actor.h b/src/meta/meta-background-actor.h
index 3008edcfd..73f81fca0 100644
--- a/src/meta/meta-background-actor.h
+++ b/src/meta/meta-background-actor.h
@@ -30,7 +30,8 @@
  * MetaBackgroundActor:
  *
  * This class handles tracking and painting the root window background.
- * By integrating with #MetaWindowGroup we can avoid painting parts of
+ * 
+ * By integrating with [class@Meta.WindowGroup] we can avoid painting parts of
  * the background that are obscured by other windows.
  */
 
diff --git a/src/meta/meta-background-content.h b/src/meta/meta-background-content.h
index a24ad809e..081c64acb 100644
--- a/src/meta/meta-background-content.h
+++ b/src/meta/meta-background-content.h
@@ -26,13 +26,6 @@
 #include "clutter/clutter.h"
 #include "meta/meta-background.h"
 
-/**
- * MetaBackgroundContent:
- *
- * This class handles tracking and painting the root window background.
- * By integrating with #MetaWindowGroup we can avoid painting parts of
- * the background that are obscured by other windows.
- */
 
 #define META_TYPE_BACKGROUND_CONTENT (meta_background_content_get_type ())
 
diff --git a/src/meta/meta-background.h b/src/meta/meta-background.h
index 550b1d986..3e58a02fe 100644
--- a/src/meta/meta-background.h
+++ b/src/meta/meta-background.h
@@ -30,7 +30,8 @@
  * MetaBackground:
  *
  * This class handles tracking and painting the root window background.
- * By integrating with #MetaWindowGroup we can avoid painting parts of
+ * 
+ * By integrating with [class@Meta.WindowGroup] we can avoid painting parts of
  * the background that are obscured by other windows.
  */
 
diff --git a/src/meta/meta-enums.h b/src/meta/meta-enums.h
index c449e3287..cb12291ff 100644
--- a/src/meta/meta-enums.h
+++ b/src/meta/meta-enums.h
@@ -343,9 +343,10 @@ typedef enum
  * @META_BUTTON_FUNCTION_CLOSE: Close
  * @META_BUTTON_FUNCTION_LAST: Marks the end of the #MetaButtonFunction enumeration
  *
- * Function a window button can have.  Note, you can't add stuff here
- * without extending the theme format to draw a new function and
- * breaking all existing themes.
+ * Function a window button can have.
+ * 
+ * Note, you can't add stuff here without extending the theme format
+ * to draw a new function and breaking all existing themes.
  */
 typedef enum
 {
diff --git a/src/meta/meta-shadow-factory.h b/src/meta/meta-shadow-factory.h
index a3aa0847c..019e74cf6 100644
--- a/src/meta/meta-shadow-factory.h
+++ b/src/meta/meta-shadow-factory.h
@@ -43,8 +43,7 @@ GType meta_shadow_get_type (void) G_GNUC_CONST;
  *  shape being shadowed, in pixels
  * @opacity: opacity of the shadow, from 0 to 255
  *
- * The #MetaShadowParams structure holds information about how to draw
- * a particular style of shadow.
+ * Information about how to draw a particular style of shadow.
  */
 
 typedef struct _MetaShadowParams MetaShadowParams;
@@ -69,9 +68,10 @@ G_DECLARE_FINAL_TYPE (MetaShadowFactory,
 /**
  * MetaShadowFactory:
  *
- * #MetaShadowFactory is used to create window shadows. It caches shadows internally
- * so that multiple shadows created for the same shape with the same radius will
- * share the same MetaShadow.
+ * Create window shadows. 
+ * 
+ * It caches shadows internally so that multiple shadows created for
+ * the same shape with the same radius will share the same [struct@Meta.Shadow].
  */
 META_EXPORT
 MetaShadowFactory *meta_shadow_factory_get_default (void);
@@ -90,9 +90,12 @@ void meta_shadow_factory_get_params (MetaShadowFactory *factory,
 
 /**
  * MetaShadow:
- * #MetaShadow holds a shadow texture along with information about how to
- * apply that texture to draw a window texture. (E.g., it knows how big the
- * unscaled borders are on each side of the shadow texture.)
+ * 
+ * Holds a shadow texture along with information about how to
+ * apply that texture to draw a window texture. 
+ * 
+ * E.g., it knows how big the unscaled borders are on each
+ * side of the shadow texture.
  */
 typedef struct _MetaShadow MetaShadow;
 
diff --git a/src/meta/meta-window-shape.h b/src/meta/meta-window-shape.h
index ec9fa7da1..5b38f736f 100644
--- a/src/meta/meta-window-shape.h
+++ b/src/meta/meta-window-shape.h
@@ -33,11 +33,12 @@ GType meta_window_shape_get_type (void) G_GNUC_CONST;
 
 /**
  * MetaWindowShape:
- * #MetaWindowShape represents a 9-sliced region with borders on all sides that
- * are unscaled, and a constant central region that is scaled. For example,
- * the regions representing two windows that are rounded rectangles,
- * with the same corner radius but different sizes, have the
- * same MetaWindowShape.
+ * 
+ * Represents a 9-sliced region with borders on all sides that
+ * are unscaled, and a constant central region that is scaled.
+ * 
+ * For example, the regions representing two windows that are rounded rectangles,
+ * with the same corner radius but different sizes, have the same MetaWindowShape.
  *
  * #MetaWindowShape is designed to be used as part of a hash table key, so has
  * efficient hash and equal functions.
diff --git a/src/meta/types.h b/src/meta/types.h
index 059ef2d10..489d7e291 100644
--- a/src/meta/types.h
+++ b/src/meta/types.h
@@ -29,10 +29,7 @@ typedef struct _MetaFrame       MetaFrame;
 typedef struct _MetaWindow      MetaWindow;
 typedef struct _MetaWorkspace   MetaWorkspace;
 typedef struct _MetaLaters      MetaLaters;
-/**
- * MetaGroup: (skip)
- *
- */
+
 typedef struct _MetaGroup       MetaGroup;
 typedef struct _MetaKeyBinding  MetaKeyBinding;
 typedef struct _MetaCursorTracker MetaCursorTracker;
diff --git a/src/wayland/meta-pointer-confinement-wayland.c b/src/wayland/meta-pointer-confinement-wayland.c
index ae6679b61..e1d344466 100644
--- a/src/wayland/meta-pointer-confinement-wayland.c
+++ b/src/wayland/meta-pointer-confinement-wayland.c
@@ -23,9 +23,9 @@
  */
 
 /**
- * SECTION:meta-pointer-confinement-wayland
- * @title: MetaPointerConfinementWayland
- * @short_description: A #MetaPointerConstraint implementing pointer confinement
+ * MetaPointerConfinementWayland:
+ *
+ * A #MetaPointerConstraint implementing pointer confinement
  *
  * A MetaPointerConfinementConstraint implements the client pointer constraint
  * "pointer confinement": the cursor should not be able to "break out" of a
diff --git a/src/wayland/meta-pointer-lock-wayland.c b/src/wayland/meta-pointer-lock-wayland.c
index dbc1b0b16..59f30affa 100644
--- a/src/wayland/meta-pointer-lock-wayland.c
+++ b/src/wayland/meta-pointer-lock-wayland.c
@@ -23,9 +23,9 @@
  */
 
 /**
- * SECTION:meta-pointer-lock-wayland
- * @title: MetaPointerLockWayland
- * @short_description: A #MetaPointerConstraint implementing pointer lock.
+ * MetaPointerLockWayland:
+ *
+ * A #MetaPointerConstraint implementing pointer lock.
  *
  * A MetaPointerLockConstraint implements the client pointer constraint "pointer
  * lock": the cursor should not make any movement.
diff --git a/src/wayland/meta-wayland-buffer.c b/src/wayland/meta-wayland-buffer.c
index bd0a17af0..4c19b8c7d 100644
--- a/src/wayland/meta-wayland-buffer.c
+++ b/src/wayland/meta-wayland-buffer.c
@@ -23,9 +23,9 @@
  */
 
 /**
- * SECTION:meta-wayland-buffer
- * @title: MetaWaylandBuffer
- * @short_description: A wrapper for wayland buffers
+ * MetaWaylandBuffer
+ * 
+ * A wrapper for wayland buffers
  *
  * #MetaWaylandBuffer is a general wrapper around wl_buffer, the basic way of
  * passing rendered data from Wayland clients to the compositor. Note that a
diff --git a/src/wayland/meta-wayland-dma-buf.c b/src/wayland/meta-wayland-dma-buf.c
index 950591c5e..dc46e6d3f 100644
--- a/src/wayland/meta-wayland-dma-buf.c
+++ b/src/wayland/meta-wayland-dma-buf.c
@@ -26,9 +26,9 @@
  */
 
 /**
- * SECTION:meta-wayland-dma-buf
- * @title: MetaWaylandDmaBuf
- * @short_description: Handles passing DMA-BUFs in Wayland
+ * MetaWaylandDmaBuf
+ * 
+ * Handles passing DMA-BUFs in Wayland
  *
  * The MetaWaylandDmaBuf namespace contains several objects and functions to
  * handle DMA-BUF buffers that are passed through from clients in Wayland (e.g.
diff --git a/src/x11/group.c b/src/x11/group.c
index c46813ec7..658642689 100644
--- a/src/x11/group.c
+++ b/src/x11/group.c
@@ -19,10 +19,9 @@
  */
 
 /**
- * SECTION:group
- * @title: MetaGroup
- * @short_description: Mutter window groups
- *
+ * MetaGroup:(skip)
+ * 
+ * Mutter window groups
  */
 
 #include "config.h"
diff --git a/src/x11/meta-x11-display.c b/src/x11/meta-x11-display.c
index b25da53fa..678177a31 100644
--- a/src/x11/meta-x11-display.c
+++ b/src/x11/meta-x11-display.c
@@ -21,9 +21,9 @@
  */
 
 /**
- * SECTION:x11-display
- * @title: MetaX11Display
- * @short_description: Mutter X display handler
+ * MetaX11Display:
+ * 
+ * Mutter X display handler
  *
  * The X11 display is represented as a #MetaX11Display struct.
  */
diff --git a/src/x11/meta-x11-errors.c b/src/x11/meta-x11-errors.c
index a9e74b3da..28e21c2db 100644
--- a/src/x11/meta-x11-errors.c
+++ b/src/x11/meta-x11-errors.c
@@ -18,9 +18,9 @@
  */
 
 /**
- * SECTION:errors
- * @title: Errors
- * @short_description: Mutter X error handling
+ * Errors:
+ * 
+ * Mutter X error handling
  */
 
 #include "config.h"
diff --git a/src/x11/window-props.c b/src/x11/window-props.c
index 3184befb0..fc9b4e3fd 100644
--- a/src/x11/window-props.c
+++ b/src/x11/window-props.c
@@ -1,8 +1,7 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
 /*
- * SECTION:window-props
- * @short_description: #MetaWindow property handling
+ * #MetaWindow property handling
  *
  * A system which can inspect sets of properties of given windows
  * and take appropriate action given their values.
diff --git a/src/x11/window-props.h b/src/x11/window-props.h
index 4f37e0c0f..ded87811f 100644
--- a/src/x11/window-props.h
+++ b/src/x11/window-props.h
@@ -1,8 +1,7 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
 /**
- * SECTION:window-props
- * @short_description: MetaWindow property handling
+ * MetaWindow property handling
  *
  * A system which can inspect sets of properties of given windows
  * and take appropriate action given their values.