mutter: Cleanup gi-docgen annotationsbilelmoussaoui/mutter-docs

14 files changed, 121 insertions, 101 deletions

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,