[mutter/wip/nielsdg/add-docs] Add some gtk-doc comments.

[Niels De Graef <nielsdg src gnome org>]

commit 0323a657138d0901ee7fb35d2b7c5b72b9d534c2
Author: Niels De Graef <nielsdegraef gmail com>
Date:   Fri Oct 19 09:15:54 2018 +0200

    Add some gtk-doc comments.

 src/backends/meta-backend.c                       |  43 ++++++++
 src/backends/meta-cursor-tracker.c                |   8 ++
 src/backends/meta-logical-monitor.c               |  19 ++++
 src/backends/meta-monitor-manager-private.h       |  54 +++++++---
 src/backends/meta-monitor-manager.c               | 114 ++++++++++++++++++++++
 src/backends/meta-pointer-constraint.c            |  26 +++++
 src/backends/meta-pointer-constraint.h            |   5 +
 src/backends/meta-renderer-view.c                 |  13 +++
 src/backends/meta-renderer.c                      |  29 ++++++
 src/backends/native/meta-clutter-backend-native.c |  12 +++
 src/backends/native/meta-monitor-manager-kms.c    |  12 +++
 src/backends/x11/meta-monitor-manager-xrandr.c    |  12 +++
 src/compositor/meta-surface-actor.c               |  10 +-
 src/compositor/meta-window-actor.c                |  15 ++-
 src/core/window.c                                 |  34 ++++++-
 src/wayland/meta-pointer-confinement-wayland.c    |  10 ++
 src/wayland/meta-pointer-lock-wayland.c           |   9 ++
 17 files changed, 408 insertions(+), 17 deletions(-)
---
diff --git a/src/backends/meta-backend.c b/src/backends/meta-backend.c
index 709d4194c..44d8ae41a 100644
--- a/src/backends/meta-backend.c
+++ b/src/backends/meta-backend.c
@@ -22,6 +22,32 @@
  *     Jasper St. Pierre <jstpierre mecheye net>
  */
 
+/**
+ * SECTION:meta-backend
+ * @title: MetaBackend
+ * @short_description: 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)
+ * - Initializing the #MetaSettings
+ * - Setting up Monitor configuration (using #MetaMonitorManager and
+ *     #MetaOrientationManage)
+ * - Input device configuration (using the #ClutterDeviceManager)
+ * - Creating the #MetaRenderer
+ * - Setting up the stage of the scene graph (using #MetaStage)
+ * - Creating the object that deals wih the cursor (using #MetaCursorTracker)
+ *     and its possible pointer constraint (using #MetaPointerConstraint)
+ * - Setting the cursor sprite (using #MetaCursorRenderer)
+ * - Interacting with logind (using the appropriate D-Bus interface)
+ * - Querying UPower (over D-Bus) to know when the lid is closed
+ * - Setup Remote Desktop / Screencasting (#MetaRemoteDesktop)
+ * - Setup the #MetaEgl object
+ *
+ * Note that the #MetaBackend is not a subclass of #ClutterBackend. It is
+ * responsible for creating the correct one, based on the display protocol
+ * used (#MetaBackendNative or #MetaBackendX11).
+ */
+
 #include "config.h"
 
 #include "backends/meta-backend-private.h"
@@ -1138,6 +1164,15 @@ meta_backend_get_client_pointer_constraint (MetaBackend *backend)
   return priv->client_pointer_constraint;
 }
 
+/**
+ * meta_backend_set_client_pointer_constraint:
+ * @backend: a #MetaBackend object.
+ * @constraint: (nullable): the client constraint to follow.
+ *
+ * Sets the current pointer constraint and removes (and unrefs) the previous
+ * one. If @constrant is %NULL, this means that there is no
+ * #MetaPointerConstraint active.
+ */
 void
 meta_backend_set_client_pointer_constraint (MetaBackend           *backend,
                                             MetaPointerConstraint *constraint)
@@ -1260,6 +1295,14 @@ meta_clutter_init (void)
   meta_backend_post_init (_backend);
 }
 
+/**
+ * meta_is_stage_views_enabled:
+ *
+ * Returns whether the #ClutterStage can be rendered using multiple stage views.
+ * In practice, this means we can define a separate framebuffer for each
+ * #MetaLogicalMonitor, rather than rendering everything into a single
+ * framebuffer. For example: in X11, onle one single framebuffer is allowed.
+ */
 gboolean
 meta_is_stage_views_enabled (void)
 {
diff --git a/src/backends/meta-cursor-tracker.c b/src/backends/meta-cursor-tracker.c
index d33fa300a..1a3501935 100644
--- a/src/backends/meta-cursor-tracker.c
+++ b/src/backends/meta-cursor-tracker.c
@@ -311,6 +311,14 @@ meta_cursor_tracker_unset_window_cursor (MetaCursorTracker *tracker)
   set_window_cursor (tracker, FALSE, NULL);
 }
 
+/**
+ * meta_cursor_tracker_set_root_cursor:
+ * @tracker: a #MetaCursorTracker object.
+ * @cursor_sprite: (transfer none): the new root cursor
+ *
+ * Sets the root cursor (the cursor that is shown if not modified by a window).
+ * The #MetaCursorTracker will take a strong reference to the sprite.
+ */
 void
 meta_cursor_tracker_set_root_cursor (MetaCursorTracker *tracker,
                                      MetaCursorSprite  *cursor_sprite)
diff --git a/src/backends/meta-logical-monitor.c b/src/backends/meta-logical-monitor.c
index 1b6151638..99a35f7f3 100644
--- a/src/backends/meta-logical-monitor.c
+++ b/src/backends/meta-logical-monitor.c
@@ -19,6 +19,25 @@
  * 02111-1307, USA.
  */
 
+/**
+ * SECTION:meta-logical-monitor
+ * @title: MetaLogicalMonitor
+ * @short_description: 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.
+ *
+ * #MetaLogicalMonitor has a single viewport, with its owns transformations
+ * (such as scaling), that are applied to all the #MetaMonitor<!-- -->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
+ * be used more easily by #MetaRendererView.
+ */
+
 #include "config.h"
 
 #include "backends/meta-logical-monitor.h"
diff --git a/src/backends/meta-monitor-manager-private.h b/src/backends/meta-monitor-manager-private.h
index 4d0aca55f..5280379ba 100644
--- a/src/backends/meta-monitor-manager-private.h
+++ b/src/backends/meta-monitor-manager-private.h
@@ -1,17 +1,5 @@
 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
 
-/**
- * \file screen-private.h  Handling of monitor configuration
- *
- * Managing multiple monitors
- * This file contains structures and functions that handle
- * multiple monitors, including reading the current configuration
- * and available hardware, and applying it.
- *
- * This interface is private to mutter, API users should look
- * at MetaScreen instead.
- */
-
 /*
  * Copyright (C) 2001 Havoc Pennington
  * Copyright (C) 2003 Rob Adams
@@ -151,6 +139,48 @@ struct _MetaMonitorManager
   MetaMonitorSwitchConfigType current_switch_config;
 };
 
+/**
+ * MetaMonitorManagerClass:
+ *
+ * @read_edid: Returns the raw Extended Display Identification Data (EDID)
+ *   for the given #MetaOutput object. Use meta_output_parse_edid() to parse
+ *   afterwards.
+ *
+ * @ensure_initial_config: Called on setup. Makes sure an initial config
+ *   is loaded.
+ *
+ * @apply_monitors_config: Tries to apply the given config using the given
+ *   method. Throws an error if something went wrong.
+ *
+ * @set_power_save_mode: Sets the #MetaPowerSave mode (for all displays).
+ *
+ * @change_backlight: Changes the backlight intensity to the given value (in
+ *   percent).
+ *
+ * @get_crtc_gamma: Queries and returns the gamma rampQueries and returns the
+ *   gamma ramp.
+ *
+ * @set_crtc_gamma: Sets custom display LUT (look up table) for each primary
+ *   color. Each table is indexed by a value that represents input intensity,
+ *   and yields a value that represents output intensity.
+ *
+ * @tiled_monitor_added: Should be called by a #MetaMonitor when it is created.
+ *
+ * @tiled_monitor_removed: Should be called by a #MetaMonitor when it is
+ *   destroyed.
+ *
+ * @is_transform_handled: vfunc for
+ *   meta_monitor_manager_is_transform_handled().
+ * @calculate_monitor_mode_scale: vfunc for
+ *   meta_monitor_manager_calculate_monitor_mode_scale().
+ * @calculate_supported_scales: vfunc for
+ *   meta_monitor_manager_calculate_supported_scales().
+ * @get_capabilities: vfunc for meta_monitor_manager_get_capabilities().
+ * @get_max_screen_size: vfunc for meta_monitor_manager_get_max_screen_size().
+ * @get_default_layout_mode: vfunc for meta_monitor_manager_get_default_layout_mode().
+ *
+ * The base class for a #MetaMonitorManager.
+ */
 struct _MetaMonitorManagerClass
 {
   MetaDBusDisplayConfigSkeletonClass parent_class;
diff --git a/src/backends/meta-monitor-manager.c b/src/backends/meta-monitor-manager.c
index cb51c2142..03496aa8c 100644
--- a/src/backends/meta-monitor-manager.c
+++ b/src/backends/meta-monitor-manager.c
@@ -23,6 +23,20 @@
  * along with this program; if not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * SECTION:meta-monitor-manager
+ * @title: MetaMonitorManager
+ * @short_description: A manager for multiple monitors
+ *
+ * #MetaMonitorManager is an abstract class which contains methods to handle
+ * multiple monitors (both #MetaMonitor and #MetaLogicalMonitor) and GPU's
+ * (#MetaGpu). Its functions include reading and/or changing the current
+ * configuration and available capabiliies.
+ *
+ * The #MetaMonitorManager also provides the "org.gnome.Mutter.DisplayConfig"
+ * DBus service, so apps like GNOME Settings can use this functionality.
+ */
+
 #include "config.h"
 
 #include "backends/meta-monitor-manager-private.h"
@@ -354,6 +368,15 @@ lid_is_closed_changed (MetaBackend *backend,
   meta_monitor_manager_lid_is_closed_changed (manager);
 }
 
+/**
+ * meta_monitor_manager_is_headless:
+ * @manager: A #MetaMonitorManager object
+ *
+ * Returns whether the monitor manager is headless, i.e. without
+ * any #MetaLogicalMonitor<!-- -->s attached to it.
+ *
+ * Returns: %TRUE if no monitors are attached, %FALSE otherwise.
+ */
 gboolean
 meta_monitor_manager_is_headless (MetaMonitorManager *manager)
 {
@@ -390,6 +413,14 @@ meta_monitor_manager_calculate_supported_scales (MetaMonitorManager          *ma
                                                     n_supported_scales);
 }
 
+/**
+ * meta_monitor_manager_get_capabilities:
+ * @manager: A #MetaMonitorManager object
+ *
+ * Queries the capabilities of the monitor manager.
+ *
+ * Returns: #MetaMonitorManagerCapability flags representing the capabilities.
+ */
 MetaMonitorManagerCapability
 meta_monitor_manager_get_capabilities (MetaMonitorManager *manager)
 {
@@ -2297,12 +2328,31 @@ meta_monitor_manager_get (void)
   return meta_backend_get_monitor_manager (backend);
 }
 
+/**
+ * meta_monitor_manager_get_num_logical_monitors:
+ * @manager: A #MetaMonitorManager object
+ *
+ * Returns the number of #MetaLogicalMonitor<!-- -->s (can be 0 in case of a
+ * headless setup).
+ *
+ * Returns: the total number of #MetaLogicalMonitor<!-- -->s.
+ */
 int
 meta_monitor_manager_get_num_logical_monitors (MetaMonitorManager *manager)
 {
   return g_list_length (manager->logical_monitors);
 }
 
+/**
+ * meta_monitor_manager_get_logical_monitors:
+ * @manager: A #MetaMonitorManager object
+ *
+ * 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.
+ *
+ * Returns: (transfer none) (nullable): the list of logical monitors.
+ */
 GList *
 meta_monitor_manager_get_logical_monitors (MetaMonitorManager *manager)
 {
@@ -2343,12 +2393,30 @@ find_monitor (MetaMonitorManager *monitor_manager,
   return NULL;
 }
 
+/**
+ * meta_monitor_manager_get_primary_monitor:
+ * @manager: A #MetaMonitorManager object
+ *
+ * Returns the primary monitor. This can be %NULL (e.g. when running headless).
+ *
+ * Returns: (transfer none) (nullable): The primary #MetaMonitor, or %NULL if
+ *          none.
+ */
 MetaMonitor *
 meta_monitor_manager_get_primary_monitor (MetaMonitorManager *manager)
 {
   return find_monitor (manager, meta_monitor_is_primary);
 }
 
+/**
+ * meta_monitor_manager_get_laptop_panel:
+ * @manager: A #MetaMonitorManager object
+ *
+ * Returns the #MetaMonitor that represents the built-in laptop panel (if
+ * applicable).
+ *
+ * Returns: (transfer none) (nullable): The laptop panel, or %NULL if none.
+ */
 MetaMonitor *
 meta_monitor_manager_get_laptop_panel (MetaMonitorManager *manager)
 {
@@ -2397,6 +2465,18 @@ meta_monitor_manager_get_monitor_from_spec (MetaMonitorManager *manager,
   return NULL;
 }
 
+/**
+ * meta_monitor_manager_get_logical_monitor_at:
+ * @manager: A #MetaMonitorManager object
+ * @x: The x-coordinate
+ * @y: The y-coordinate
+ *
+ * Finds the #MetaLogicalMonitor at the given @x and @y coordinates in the
+ * total layout.
+ *
+ * Returns: (transfer none) (nullable): The #MetaLogicalMonitor at the given
+ *          point, or %NULL if none.
+ */
 MetaLogicalMonitor *
 meta_monitor_manager_get_logical_monitor_at (MetaMonitorManager *manager,
                                              float               x,
@@ -2415,6 +2495,17 @@ meta_monitor_manager_get_logical_monitor_at (MetaMonitorManager *manager,
   return NULL;
 }
 
+/**
+ * meta_monitor_manager_get_logical_monitor_from_rect:
+ * @manager: A #MetaMonitorManager object
+ * @rect: The rectangle
+ *
+ * Finds the #MetaLogicalMonitor which has the largest area in common with the
+ * given @rect in the total layout.
+ *
+ * Returns: (transfer none) (nullable): The #MetaLogicalMonitor which
+ *          corresponds the most to the given @rect, or %NULL if none.
+ */
 MetaLogicalMonitor *
 meta_monitor_manager_get_logical_monitor_from_rect (MetaMonitorManager *manager,
                                                     MetaRectangle      *rect)
@@ -2474,12 +2565,29 @@ meta_monitor_manager_get_logical_monitor_neighbor (MetaMonitorManager  *manager,
   return NULL;
 }
 
+/**
+ * meta_monitor_manager_get_monitors:
+ * @manager: A #MetaMonitorManager object
+ *
+ * Returns the list of #MetaMonitor<!-- -->s. See also
+ * meta_monitor_manager_get_logical_monitors() for a list of
+ * #MetaLogicalMonitor<!-- -->s.
+ *
+ * Returns: (transfer none) (nullable): the list of #MetaMonitor<!-- -->s.
+ */
 GList *
 meta_monitor_manager_get_monitors (MetaMonitorManager *manager)
 {
   return manager->monitors;
 }
 
+/**
+ * meta_monitor_manager_get_capabilities:
+ * @manager: A #MetaMonitorManager object
+ *
+ * Should only be called by subclasses. Adds a #MetaGpu to the internal list of
+ * GPU's.
+ */
 void
 meta_monitor_manager_add_gpu (MetaMonitorManager *manager,
                               MetaGpu            *gpu)
@@ -2890,6 +2998,12 @@ meta_monitor_manager_get_monitor_for_connector (MetaMonitorManager *manager,
   return -1;
 }
 
+/**
+ * meta_monitor_manager_get_is_builtin_display_on:
+ * @manager: A #MetaMonitorManager object
+ *
+ * Returns whether the built-in display (i.e. a laptop panel) is turned on.
+ */
 gboolean
 meta_monitor_manager_get_is_builtin_display_on (MetaMonitorManager *manager)
 {
diff --git a/src/backends/meta-pointer-constraint.c b/src/backends/meta-pointer-constraint.c
index 40ee3d32f..55ca9f023 100644
--- a/src/backends/meta-pointer-constraint.c
+++ b/src/backends/meta-pointer-constraint.c
@@ -22,6 +22,19 @@
  *     Jonas Ådahl <jadahl gmail com>
  */
 
+/**
+ * SECTION:meta-pointer-constraint
+ * @title: MetaPointerConstraint
+ * @short_description: Pointer client constraints.
+ *
+ * A MetaPointerConstraint can be used to implement any kind of pointer
+ * constraint as requested by a client, such as cursor lock.
+ *
+ * Examples of pointer constraints are "pointer confinement" and "pointer
+ * locking" (as defined in the wayland pointer constraint protocol extension),
+ * which restrict movement in relation to a given client.
+ */
+
 #include "config.h"
 
 #include "backends/meta-pointer-constraint.h"
@@ -40,6 +53,19 @@ meta_pointer_constraint_class_init (MetaPointerConstraintClass *klass)
 {
 }
 
+/**
+ * meta_pointer_constraint_constrain:
+ * @constraint: a #MetaPointerConstraint.
+ * @device; the device of the pointer.
+ * @time: the timestamp (in ms) of the event.
+ * @prev_x: X-coordinate of the previous pointer position.
+ * @prev_y: Y-coordinate of the previous pointer position.
+ * @x: The modifiable X-coordinate to which the pointer would like to go to.
+ * @y: The modifiable Y-coordinate to which the pointer would like to go to.
+ *
+ * Constrains the pointer movement from point (@prev_x, @prev_y) to (@x, @y),
+ * if needed.
+ */
 void
 meta_pointer_constraint_constrain (MetaPointerConstraint *constraint,
                                    ClutterInputDevice    *device,
diff --git a/src/backends/meta-pointer-constraint.h b/src/backends/meta-pointer-constraint.h
index 01bc13758..ed0b025b5 100644
--- a/src/backends/meta-pointer-constraint.h
+++ b/src/backends/meta-pointer-constraint.h
@@ -35,6 +35,11 @@ G_BEGIN_DECLS
 G_DECLARE_DERIVABLE_TYPE (MetaPointerConstraint, meta_pointer_constraint,
                           META, POINTER_CONSTRAINT, GObject);
 
+/**
+ * MetaPointerConstraintClass:
+ * @constrain: the virtual function pointer for
+ *             meta_pointer_constraint_constrain().
+ */
 struct _MetaPointerConstraintClass
 {
   GObjectClass parent_class;
diff --git a/src/backends/meta-renderer-view.c b/src/backends/meta-renderer-view.c
index 19ab9efc8..d93bd99ac 100644
--- a/src/backends/meta-renderer-view.c
+++ b/src/backends/meta-renderer-view.c
@@ -15,6 +15,19 @@
  * License along with this library. If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * SECTION:meta-renderer-view
+ * @title: MetaRendererView
+ * @short_description: 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
+ * #MetaLogicalMonitor. By splitting up the rendering into different parts and
+ * attaching it to a #MetaLogicalMonitor, we can do the rendering so that each
+ * renderer view is responsible for applying the right #MetaMonitorTransform
+ * (which can imply scaling).
+ */
+
 #include "config.h"
 
 #include "backends/meta-renderer-view.h"
diff --git a/src/backends/meta-renderer.c b/src/backends/meta-renderer.c
index 191897e64..01f6a0015 100644
--- a/src/backends/meta-renderer.c
+++ b/src/backends/meta-renderer.c
@@ -22,6 +22,18 @@
  *     Jonas Ådahl <jadahl gmail com>
  */
 
+/**
+ * SECTION:meta-renderer
+ * @title: MetaRenderer
+ * @short_description: Keeps track of the different renderer views.
+ *
+ * A MetaRenderer object contains 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
+ * #MetaLogicalMonitor<!-- -->s in the #MetaMonitorManager, and creating a
+ * renderer view for each.
+ */
+
 #include "config.h"
 
 #include "backends/meta-renderer.h"
@@ -51,6 +63,13 @@ meta_renderer_create_view (MetaRenderer       *renderer,
                                                           logical_monitor);
 }
 
+/**
+ * meta_renderer_rebuild_views:
+ * @renderer: a #MetaRenderer object
+ *
+ * Rebuilds the internal list of #MetaRendererView objects (this also means the
+ * original list is unconditionally freed).
+ */
 void
 meta_renderer_rebuild_views (MetaRenderer *renderer)
 {
@@ -87,6 +106,16 @@ meta_renderer_set_legacy_view (MetaRenderer     *renderer,
   priv->views = g_list_append (priv->views, legacy_view);
 }
 
+/**
+ * meta_renderer_get_views:
+ * @renderer: a #MetaRenderer object
+ *
+ * Returns a list of #MetaRendererView objects, each dealing with a part of the
+ * stage.
+ *
+ * Returns: (transfer-none) (element-type MetaRendererView): a list of
+ * #MetaRendererView objects.
+ */
 GList *
 meta_renderer_get_views (MetaRenderer *renderer)
 {
diff --git a/src/backends/native/meta-clutter-backend-native.c 
b/src/backends/native/meta-clutter-backend-native.c
index be86eb50e..6c3d34d18 100644
--- a/src/backends/native/meta-clutter-backend-native.c
+++ b/src/backends/native/meta-clutter-backend-native.c
@@ -22,6 +22,18 @@
  *     Jonas Ådahl <jadahl gmail com>
  */
 
+/**
+ * SECTION:meta-clutter-backend-native
+ * @title: MetaClutterBackendNatve
+ * @short_description: 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
+ * renders using the #CoglRenderer.
+ *
+ * Note that MetaClutterBackendNative is something different than e #MetBackend.
+ */
+
 #include "config.h"
 
 #include "backends/native/meta-clutter-backend-native.h"
diff --git a/src/backends/native/meta-monitor-manager-kms.c b/src/backends/native/meta-monitor-manager-kms.c
index 48b2d374d..27db0140c 100644
--- a/src/backends/native/meta-monitor-manager-kms.c
+++ b/src/backends/native/meta-monitor-manager-kms.c
@@ -22,6 +22,18 @@
  * Author: Giovanni Campagna <gcampagn redhat com>
  */
 
+/**
+ * SECTION:meta-monitor-manager-kms
+ * @title: MetaMonitorManagerKms
+ * @short_description: A subclass of #MetaMonitorManager using Linux DRM
+ *
+ * #MetaMonitorManagerKms is a subclass of #MetaMonitorManager which
+ * implements its functionality "natively": it uses the appropriate
+ * functions of the Linux DRM kernel module and using a udev client.
+ *
+ * See also #MetaMonitorManagerXrandr for an implementation using XRandR.
+ */
+
 #include "config.h"
 
 #include "backends/native/meta-monitor-manager-kms.h"
diff --git a/src/backends/x11/meta-monitor-manager-xrandr.c b/src/backends/x11/meta-monitor-manager-xrandr.c
index 21ee50e97..246e60334 100644
--- a/src/backends/x11/meta-monitor-manager-xrandr.c
+++ b/src/backends/x11/meta-monitor-manager-xrandr.c
@@ -23,6 +23,18 @@
  * along with this program; if not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * SECTION:meta-monitor-manager-xrandr
+ * @title: MetaMonitorManagerXrandr
+ * @short_description: A subclass of #MetaMonitorManager using XRadR
+ *
+ * #MetaMonitorManagerXrandr is a subclass of #MetaMonitorManager which
+ * implements its functionality using the RandR X protocol.
+ *
+ * See also #MetaMonitorManagerKms for a native implementation using Linux DRM
+ * and udev.
+ */
+
 #include "config.h"
 
 #include "backends/x11/meta-monitor-manager-xrandr.h"
diff --git a/src/compositor/meta-surface-actor.c b/src/compositor/meta-surface-actor.c
index 256215373..6f36ba13e 100644
--- a/src/compositor/meta-surface-actor.c
+++ b/src/compositor/meta-surface-actor.c
@@ -5,8 +5,14 @@
  * @title: MetaSurfaceActor
  * @short_description: An actor representing a surface in the scene graph
  *
- * A surface can be either a shaped texture, or a group of shaped texture,
- * used to draw the content of a window.
+ * MetaSurfaceActor is an abstract class which represents a surface in the
+ * Clutter scene graph. A subclass can implement the specifics of a surface
+ * depending on the way it is handled by a display protocol.
+ *
+ * An important feature of #MetaSurfaceActor is that it allows you to set an
+ * "input region": all events that occur in the surface, but outside of the
+ * input region are to be explicitly ignored. By default, this region is to
+ * %NULL, which means events on the whole surface is allowed.
  */
 
 #include "config.h"
diff --git a/src/compositor/meta-window-actor.c b/src/compositor/meta-window-actor.c
index 4456e1892..5c9ce1e82 100644
--- a/src/compositor/meta-window-actor.c
+++ b/src/compositor/meta-window-actor.c
@@ -3,7 +3,20 @@
 /**
  * SECTION:meta-window-actor
  * @title: MetaWindowActor
- * @short_description: An actor representing a top-level window in the scene graph
+ * @short_description: 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
+ * API, and the #MetaCompositor that handles it.  For the actual content of the
+ * window, it contains a #MetaSurfaceActor.
+ *
+ * #MetaWindowActor takes care of the rendering features you need for your
+ * window. For example, it will take the windows' requested opacity and use
+ * that for clutter_actor_set_opacity(). Furthermore, it will also draw a
+ * shadow around the window (using #MetaShadow) and deal with synchronization
+ * between events of the window and the actual render loop. See
+ * MetaWindowActor::first-frame for an example of the latter.
  */
 
 #include "config.h"
diff --git a/src/core/window.c b/src/core/window.c
index 3018c1b7b..aaa4fe4a9 100644
--- a/src/core/window.c
+++ b/src/core/window.c
@@ -21,9 +21,39 @@
  */
 
 /**
- * SECTION:window
+ * SECTION:meta-window
  * @title: MetaWindow
- * @short_description: Mutter X managed windows
+ * @short_description: 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, an icon, 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
+ * 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().
+ *
+ * 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()
+ *
+ * Each #MetaWindow is part of either one or all #MetaWorkspace<!-- -->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().
+ *
+ * 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.
+ *
+ * To integrate within the Clutter scene graph, which deals with the actual
+ * rendering, each #MetaWindow will be part of a #MetaWindowActor.
  */
 
 #include "config.h"
diff --git a/src/wayland/meta-pointer-confinement-wayland.c b/src/wayland/meta-pointer-confinement-wayland.c
index b8a900467..4c1a9f937 100644
--- a/src/wayland/meta-pointer-confinement-wayland.c
+++ b/src/wayland/meta-pointer-confinement-wayland.c
@@ -22,6 +22,16 @@
  *     Jonas Ådahl <jadahl gmail com>
  */
 
+/**
+ * SECTION:meta-pointer-confinement-wayland
+ * @title: MetaPointerConfinementWayland
+ * @short_description: 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
+ * certain area defined by the client requesting it.
+ */
+
 #include "config.h"
 
 #include "wayland/meta-pointer-confinement-wayland.h"
diff --git a/src/wayland/meta-pointer-lock-wayland.c b/src/wayland/meta-pointer-lock-wayland.c
index a9098d529..08c2789bc 100644
--- a/src/wayland/meta-pointer-lock-wayland.c
+++ b/src/wayland/meta-pointer-lock-wayland.c
@@ -22,6 +22,15 @@
  *     Jonas Ådahl <jadahl gmail com>
  */
 
+/**
+ * SECTION:meta-pointer-lock-wayland
+ * @title: MetaPointerLockWayland
+ * @short_description: A #MetaPointerConstraint implementing pointer lock.
+ *
+ * A MetaPointerLockConstraint implements the client pointer constraint "pointer
+ * lock": the cursor should not make any movement.
+ */
+
 #include "config.h"
 
 #include "wayland/meta-pointer-lock-wayland.h"