mutter: Cleanup gi-docgen annotations

Part-of: <https://gitlab.gnome.org/GNOME/mutter/-/merge_requests/2939>

src/backends/meta-backend.c

@@ -23,9 +23,9 @@
  */
 
 /**
- * SECTION:meta-backend
+ * MetaBackend:
- * @title: MetaBackend
+ * 
- * @short_description: Handles monitor config, modesetting, cursor sprites, ...
+ * 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)

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
+ * MetaBarrier:
- * @Title: MetaBarrier
+ * 
- * @Short_Description: Pointer barriers
+ * Pointer barriers
  */
 
 #include "config.h"

src/backends/meta-color-manager.c

@@ -17,10 +17,10 @@
  */
 
 /**
- * SECTION:meta-color-manager
+ * MetaColorManager:
- * @title: MetaColorManager
+ * 
- * @short_description: Interfaces for managing color-related properties like
+ * Interfaces for managing color-related properties like
- *   color look-up tables and color spaces.
+ * 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

src/backends/meta-cursor-tracker.c

@@ -20,11 +20,10 @@
  */
 
 /**
- * SECTION:cursor-tracker
+ * MetaCursorTracker:
- * @title: MetaCursorTracker
+ * 
- * @short_description: Mutter cursor tracking helper. Originally only
+ * Mutter cursor tracking helper. Originally only tracking
- *                     tracking the cursor image, now more of a "core
+ * the cursor image, now more of a "core pointer abstraction"
- *                     pointer abstraction"
  */
 
 #include "config.h"

src/backends/meta-idle-monitor.c

@@ -21,9 +21,9 @@
  */
 
 /**
- * SECTION:idle-monitor
+ * MetaIdleMonitor:
- * @title: MetaIdleMonitor
+ * 
- * @short_description: Mutter idle counter (similar to X's IDLETIME)
+ * Mutter idle counter (similar to X's IDLETIME)
  */
 
 #include "config.h"

src/backends/meta-input-settings.c

@@ -20,9 +20,9 @@
  */
 
 /**
- * SECTION:input-settings
+ * MetaInputSettings:
- * @title: MetaInputSettings
+ * 
- * @short_description: Mutter input device configuration
+ * Mutter input device configuration
  */
 
 #include "config.h"

src/backends/meta-logical-monitor.c

@@ -20,21 +20,21 @@
  */
 
 /**
- * SECTION:meta-logical-monitor
+ * MetaLogicalMonitor:
- * @title: MetaLogicalMonitor
+ * 
- * @short_description: An abstraction for a monitor(set) and its configuration.
+ * 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.
  */
 

src/backends/meta-monitor-manager.c

@@ -25,9 +25,9 @@
  */
 
 /**
- * SECTION:meta-monitor-manager
+ * MetaMonitorManager:
- * @title: MetaMonitorManager
+ * 
- * @short_description: A manager for multiple monitors
+ * 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.
  *
@@ -3462,11 +3462,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)

src/backends/meta-pointer-constraint.c

@@ -23,9 +23,9 @@
  */
 
 /**
- * SECTION:meta-pointer-constraint
+ * MetaPointerConstraint:
- * @title: MetaPointerConstraint
+ * 
- * @short_description: Pointer client constraints.
+ * Pointer client constraints.
  *
  * A MetaPointerConstraint can be used to implement any kind of pointer
  * constraint as requested by a client, such as cursor lock.

src/backends/meta-renderer-view.c

@@ -16,9 +16,9 @@
  */
 
 /**
- * SECTION:meta-renderer-view
+ * MetaRendererView:
- * @title: MetaRendererView
+ * 
- * @short_description: Renders (a part of) the global stage.
+ * 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

src/backends/meta-renderer.c

@@ -23,13 +23,13 @@
  */
 
 /**
- * SECTION:meta-renderer
+ * MetaRenderer:
- * @title: MetaRenderer
+ * 
- * @short_description: Keeps track of the different renderer views.
+ * 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

src/backends/native/meta-backend-native.c

@@ -23,9 +23,9 @@
  */
 
 /**
- * SECTION:meta-backend-native
+ * MetaBackendNative:
- * @title: MetaBackendNative
+ * 
- * @short_description: A native (KMS/evdev) MetaBackend
+ * 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

src/backends/native/meta-barrier-native.c

@@ -23,9 +23,9 @@
  */
 
 /**
- * SECTION:barrier-native
+ * MetaBarrierImplNative:
- * @Title: MetaBarrierImplNative
+ * 
- * @Short_Description: Pointer barriers implementation for the native backend
+ * Pointer barriers implementation for the native backend
  */
 
 #include "config.h"

src/backends/native/meta-clutter-backend-native.c

@@ -23,9 +23,9 @@
  */
 
 /**
- * SECTION:meta-clutter-backend-native
+ * MetaClutterBackendNative:
- * @title: MetaClutterBackendNatve
+ * 
- * @short_description: A native backend which renders using EGL.
+ * 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

src/backends/native/meta-monitor-manager-native.c

@@ -23,9 +23,9 @@
  */
 
 /**
- * SECTION:meta-monitor-manager-native
+ * MetaMonitorManagerNative:
- * @title: MetaMonitorManagerNative
+ * 
- * @short_description: A subclass of #MetaMonitorManager using Linux DRM
+ * A subclass of #MetaMonitorManager using Linux DRM
  *
  * #MetaMonitorManagerNative is a subclass of #MetaMonitorManager which
  * implements its functionality "natively": it uses the appropriate

src/backends/x11/meta-backend-x11.c

@@ -23,9 +23,9 @@
  */
 
 /**
- * SECTION:meta-backend-x11
+ * MetaBackendX11:
- * @title: MetaBackendX11
+ * 
- * @short_description: A X11 MetaBackend
+ * A X11 MetaBackend
  *
  * MetaBackendX11 is an implementation of #MetaBackend using X and X
  * extensions, like XInput and XKB.

src/backends/x11/meta-barrier-x11.c

@@ -24,9 +24,9 @@
  */
 
 /**
- * SECTION:barrier-x11
+ * MetaBarrierImplX11:
- * @Title: MetaBarrierImplX11
+ * 
- * @Short_Description: Pointer barriers implementation for X11
+ * Pointer barriers implementation for X11
  */
 
 #include "config.h"

src/backends/x11/meta-monitor-manager-xrandr.c

@@ -25,9 +25,9 @@
  */
 
 /**
- * SECTION:meta-monitor-manager-xrandr
+ * MetaMonitorManagerXrandr:
- * @title: MetaMonitorManagerXrandr
+ * 
- * @short_description: A subclass of #MetaMonitorManager using XRadR
+ * A subclass of #MetaMonitorManager using XRadR
  *
  * #MetaMonitorManagerXrandr is a subclass of #MetaMonitorManager which
  * implements its functionality using the RandR X protocol.

src/compositor/compositor.c

@@ -1,9 +1,9 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
 /**
- * SECTION:compositor
+ * MetaCompositor:
- * @Title: MetaCompositor
+ * 
- * @Short_Description: Compositor API
+ * 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.

src/compositor/meta-background-content.c

@@ -21,13 +21,13 @@
 
 
 /**
- * SECTION:meta-background-content
+ * MetaBackgroundContent:
- * @title: MetaBackgroundContent
- * @short_description: ClutterContent for painting the root window background
  *
- */
+ * 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

src/compositor/meta-background-group.c

@@ -1,9 +1,9 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
 /**
- * SECTION:meta-background-group
+ * MetaBackgroundGroup:
- * @title: MetaBackgroundGroup
+ * 
- * @short_description: Container for background actors
+ * Container for background actors
  *
  * This class is a subclass of ClutterActor with special handling for
  * MetaBackgroundActor/MetaBackgroundGroup when painting children.

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
+ * Caches loading of textures for backgrounds.
- * nothing background specific about it, other than it is tuned to work well for
+ * 
- * large images as typically are used 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
+ * image that is already in the process of loading or loaded.
- * case, what is returned is a #MetaBackgroundImage which can be dereferenced
+ * 
- * to get a #CoglTexture. If meta_background_image_is_loaded() returns %TRUE,
+ * In either case, what is returned is a [class@Meta.BackgroundImage] which can be dereferenced
- * the background is loaded, otherwise the MetaBackgroundImage::loaded
+ * 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.
  *

src/compositor/meta-cullable.c

@@ -57,9 +57,9 @@ region_apply_transform_expand_maybe_ref (cairo_region_t    *region,
 }
 
 /**
- * SECTION:meta-cullable
+ * MetaCullable:
- * @title: MetaCullable
+ * 
- * @short_description: CPU culling operations for efficient drawing
+ * 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

src/compositor/meta-dnd-actor.c

@@ -19,9 +19,9 @@
  */
 
 /**
- * SECTION:meta-dnd-actor
+ * MetaDnDActor:
- * @title: MetaDnDActor
+ * 
- * @short_description: Actor for painting the drag and drop surface
+ * Actor for painting the drag and drop surface
  *
  */
 

src/compositor/meta-feedback-actor.c

@@ -19,9 +19,9 @@
  */
 
 /**
- * SECTION:meta-feedback-actor
+ * MetaFeedbackActor:
- * @title: MetaFeedbackActor
+ * 
- * @short_description: Actor for painting user interaction feedback
+ * Actor for painting user interaction feedback
  */
 
 #include "config.h"

src/compositor/meta-plugin.c

@@ -20,10 +20,9 @@
  */
 
 /**
- * SECTION:meta-plugin
+ * MetaPlugin:
- * @title: MetaPlugin
+ * 
- * @short_description: Entry point for plugins
+ * Entry point for plugins
- *
  */
 
 #include "config.h"

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
+ * size of the region. 
- * different sizes with the same extracted #MetaWindowShape the
+ * 
- * size needs to be passed in here.)
+ * 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,

src/compositor/meta-shaped-texture.c

@@ -22,9 +22,9 @@
  */
 
 /**
- * SECTION:meta-shaped-texture
+ * MetaShapedTexture:
- * @title: MetaShapedTexture
+ * 
- * @short_description: A ClutterContent which draws a shaped texture
+ * 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

src/compositor/meta-surface-actor.c

@@ -1,9 +1,9 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
 /**
- * SECTION:meta-surface-actor
+ * MetaSurfaceActor:
- * @title: MetaSurfaceActor
+ * 
- * @short_description: An actor representing a surface in the scene graph
+ * 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

src/compositor/meta-texture-mipmap.h

@@ -28,8 +28,9 @@
 G_BEGIN_DECLS
 
 /**
- * SECTION:MetaTextureMipmap
+ * MetaTextureMipmap:
- * @short_description: mipmap handling for textures
+ * 
+ * Mipmap handling for textures
  *
  * A #MetaTextureMipmap is used to get GL mipmaps for a texture
  */

src/compositor/meta-window-actor.c

@@ -1,10 +1,9 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
 /**
- * SECTION:meta-window-actor
+ * MetaWindowActor:
- * @title: MetaWindowActor
+ * 
- * @short_description: An actor representing a top-level window in the scene
+ * An actor representing a top-level window in the scene graph
- *   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

src/core/bell.c

@@ -21,8 +21,9 @@
  */
 
 /*
- * SECTION:bell
+ * bell:
- * @short_description: Ring the bell or flash the screen
+ * 
+ * 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

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,

src/core/display.c

@@ -21,9 +21,9 @@
  */
 
 /**
- * SECTION:display
+ * MetaDisplay:
- * @title: MetaDisplay
+ * 
- * @short_description: Mutter display representation
+ * 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
+   * The signal will be emitted to indicate that the compositor 
-   * that the compositor should show a message during restart. This is
+   * should show a message during restart.
-   * emitted when meta_restart() is called, either by Mutter
+   * 
-   * internally or by the embedding compositor.  The message should be
+   * 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
+   * The signal is emitted to indicate that compositor
-   * should reexec the process. This is
+   * should reexec the process.
-   * emitted when meta_restart() is called, either by Mutter
+   * 
-   * internally or by the embedding compositor. See also
+   * This is emitted when [func@Meta.restart] is called,
-   * ::show-restart-message.
+   * 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

src/core/keybindings.c

@@ -22,9 +22,9 @@
  */
 
 /**
- * SECTION:keybindings
+ * MetaKeybinding:
- * @Title: MetaKeybinding
+ * 
- * @Short_Description: Key bindings
+ * Key bindings
  */
 
 #include "config.h"

src/core/meta-gesture-tracker.c

@@ -20,9 +20,9 @@
  */
 
 /**
- * SECTION:gesture-tracker
+ * MetaGestureTracker:
- * @Title: MetaGestureTracker
+ * 
- * @Short_Description: Manages gestures on windows/desktop
+ * Manages gestures on windows/desktop
  *
  * Forwards touch events to clutter actors, and accepts/rejects touch sequences
  * based on the outcome of those.

src/core/prefs.c

@@ -21,9 +21,9 @@
  */
 
 /**
- * SECTION:prefs
+ * Preferences:
- * @title: Preferences
+ * 
- * @short_description: Mutter preferences
+ * Mutter preferences
  */
 
 #include "config.h"

src/core/restart-helper.c

@@ -1,8 +1,9 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
 /*
- * SECTION:restart-helper
+ * restart-helper
- * @short_description: helper program during a restart
+ * 
+ * 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

src/core/restart.c

@@ -18,8 +18,9 @@
  */
 
 /*
- * SECTION:restart
+ * restart:
- * @short_description: Smoothly restart the compositor
+ *
+ * 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
+ * Starts the process of restarting the compositor.
- * involvement here is to make the restart visually smooth for the
+ * 
- * user - it cannot itself safely reexec a program that embeds libmuttter.
+ * 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
+ * signals 
- * message passed here on the Clutter stage, and ::restart to actually
+ * 
- * reexec the compositor.
+ * - [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

src/core/stack-tracker.c

@@ -1,8 +1,9 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
 /*
- * SECTION:stack-tracker
+ * stack-tracker:
- * @short_description: Track stacking order for compositor
+ *
+ * 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

src/core/stack.c

@@ -1,8 +1,9 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
 /*
- * SECTION:stack
+ * stack:
- * @short_description: Which windows cover which other windows
+ *
+ * Which windows cover which other windows
  */
 
 /*

src/core/stack.h

@@ -22,8 +22,9 @@
 #define META_STACK_H
 
 /**
- * SECTION:stack
+ * stack:
- * @short_description: Which windows cover which other windows
+ * 
+ * Which windows cover which other windows
  *
  * There are two factors that determine window position.
  *

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
+ * Stop printing log messages for the given topic @topic.
- * that this method does not stack with meta_add_verbose_topic();
+ * 
- * i.e. if two calls to meta_add_verbose_topic() for the same
+ * Note that this method does not stack with [func@Meta.add_verbose_topic];
- * topic are made, one call to meta_remove_verbose_topic() will
+ * 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

src/core/window.c

@@ -21,39 +21,40 @@
  */
 
 /**
- * SECTION:meta-window
+ * MetaWindow:
- * @title: MetaWindow
+ * 
- * @short_description: A display-agnostic abstraction for a window.
+ * 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()
+ * - Minimizing: [method@Meta.Window.minimize] / [method@Meta.Window.unminimize]
- * - Fullscreen: meta_window_make_fullscreen() / meta_window_unmake_fullscreen()
+ * - Maximizing: [method@Meta.Window.maximize] / [method@Meta.Window.unmaximize]
- *               / meta_window_is_fullscreen()
+ * - 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
+ * [method@Meta.Window.activate_with_workspace], and query on which workspace it is
- * located using meta_window_located_on_workspace(). The workspace it is part
+ * located using [method@Meta.Window.located_on_workspace]. The workspace it is part
- * of can be obtained using meta_window_get_workspace().
+ * 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"
@@ -714,9 +715,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
+   * have changed.
-   * position of the toplevel window has changed, or when
+   * 
-   * the position of the client window has 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",
@@ -745,8 +748,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
+   * have changed.
-   * size of the toplevel window has changed, or when the
+   * 
+   * 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] =
@@ -3966,6 +3971,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
@@ -4418,9 +4424,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
+ * as the edge of the window.
- * area that we or the client adds to the window, or any area that the
+ * 
- * client adds to draw a client-side shadow.
+ * 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,
@@ -5279,9 +5286,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
+ * Gets the location of the icon corresponding to the window.
- * will be provided set by the task bar or other user interface element
+ * 
- * displaying the icon, and is relative to the root 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.
  */
@@ -5307,8 +5315,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
+ * Sets or unsets the location of the icon corresponding to the window.
- * set, the location should correspond to a dock, task bar or other user
+ * 
+ * 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
@@ -5950,7 +5959,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)
@@ -6235,8 +6245,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
+ * interacted with this window.
- * for non-override-redirect windows.
+ * 
+ * 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,
@@ -6414,8 +6425,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
+ * Determines if the window should be drawn with a focused appearance.
- * true for focused windows but also true for windows with a focused modal
+ * 
+ * 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
@@ -6495,7 +6507,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.
  *
@@ -6537,9 +6550,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 *
@@ -6555,9 +6568,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 *
@@ -6998,8 +7011,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
  */
@@ -7029,8 +7043,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
  */

src/core/workspace.c

@@ -20,9 +20,9 @@
  */
 
 /**
- * SECTION:workspace
+ * MetaWorkspace:
- * @title:MetaWorkspace
+ * 
- * @short_description:Workspaces
+ * 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,

src/meta/common.h

@@ -34,9 +34,9 @@
 #include "meta/meta-enums.h"
 
 /**
- * SECTION:common
+ * Common:
- * @Title: Common
+ * 
- * @Short_Description: Mutter common types
+ * Mutter common types
  */
 
 /* This is set in stone and also hard-coded in GDK. */

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

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

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

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
+ * Function a window button can have.
- * without extending the theme format to draw a new function and
+ * 
- * breaking all existing themes.
+ * Note, you can't add stuff here without extending the theme format
+ * to draw a new function and breaking all existing themes.
  */
 typedef enum
 {

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
+ * Information about how to draw a particular style of shadow.
- * 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
+ * Create window shadows. 
- * so that multiple shadows created for the same shape with the same radius will
+ * 
- * share the same MetaShadow.
+ * 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
+ * Holds a shadow texture along with information about how to
- * unscaled borders are on each side of the shadow texture.)
+ * 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;
 

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,
+ * Represents a 9-sliced region with borders on all sides that
- * the regions representing two windows that are rounded rectangles,
+ * are unscaled, and a constant central region that is scaled.
- * with the same corner radius but different sizes, have the
+ * 
- * same MetaWindowShape.
+ * 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.

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;

src/wayland/meta-pointer-confinement-wayland.c

@@ -23,9 +23,9 @@
  */
 
 /**
- * SECTION:meta-pointer-confinement-wayland
+ * MetaPointerConfinementWayland:
- * @title: MetaPointerConfinementWayland
+ *
- * @short_description: A #MetaPointerConstraint implementing pointer confinement
+ * 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

src/wayland/meta-pointer-lock-wayland.c

@@ -23,9 +23,9 @@
  */
 
 /**
- * SECTION:meta-pointer-lock-wayland
+ * MetaPointerLockWayland:
- * @title: MetaPointerLockWayland
+ *
- * @short_description: A #MetaPointerConstraint implementing pointer lock.
+ * A #MetaPointerConstraint implementing pointer lock.
  *
  * A MetaPointerLockConstraint implements the client pointer constraint "pointer
  * lock": the cursor should not make any movement.

src/wayland/meta-wayland-buffer.c

@@ -23,9 +23,9 @@
  */
 
 /**
- * SECTION:meta-wayland-buffer
+ * MetaWaylandBuffer
- * @title: MetaWaylandBuffer
+ * 
- * @short_description: A wrapper for wayland buffers
+ * 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

src/wayland/meta-wayland-dma-buf.c

@@ -26,9 +26,9 @@
  */
 
 /**
- * SECTION:meta-wayland-dma-buf
+ * MetaWaylandDmaBuf
- * @title: MetaWaylandDmaBuf
+ * 
- * @short_description: Handles passing DMA-BUFs in Wayland
+ * 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.

src/x11/group.c

@@ -19,10 +19,9 @@
  */
 
 /**
- * SECTION:group
+ * MetaGroup:(skip)
- * @title: MetaGroup
+ * 
- * @short_description: Mutter window groups
+ * Mutter window groups
- *
  */
 
 #include "config.h"

src/x11/meta-x11-display.c

@@ -21,9 +21,9 @@
  */
 
 /**
- * SECTION:x11-display
+ * MetaX11Display:
- * @title: MetaX11Display
+ * 
- * @short_description: Mutter X display handler
+ * Mutter X display handler
  *
  * The X11 display is represented as a #MetaX11Display struct.
  */

src/x11/meta-x11-errors.c

@@ -18,9 +18,9 @@
  */
 
 /**
- * SECTION:errors
+ * Errors:
- * @title: Errors
+ * 
- * @short_description: Mutter X error handling
+ * Mutter X error handling
  */
 
 #include "config.h"

src/x11/window-props.c

@@ -1,8 +1,7 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
 /*
- * SECTION:window-props
+ * #MetaWindow property handling
- * @short_description: #MetaWindow property handling
  *
  * A system which can inspect sets of properties of given windows
  * and take appropriate action given their values.

src/x11/window-props.h

@@ -1,8 +1,7 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
 /**
- * SECTION:window-props
+ * MetaWindow property handling
- * @short_description: MetaWindow property handling
  *
  * A system which can inspect sets of properties of given windows
  * and take appropriate action given their values.