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

[Niels De Graef <nielsdg src gnome org>]

commit eb5c43f77476375710f69bef908673fdc55811b7
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                       | 32 +++++++++++++++++++++++
 src/backends/meta-cursor-tracker.c                |  8 ++++++
 src/backends/meta-logical-monitor.c               | 15 +++++++++++
 src/backends/meta-pointer-constraint.c            | 32 +++++++++++++++++++++++
 src/backends/meta-renderer-view.c                 | 12 +++++++++
 src/backends/meta-renderer.c                      | 29 ++++++++++++++++++++
 src/backends/native/meta-clutter-backend-native.c | 11 ++++++++
 src/wayland/meta-pointer-confinement-wayland.c    | 10 +++++++
 src/wayland/meta-pointer-lock-wayland.c           |  9 +++++++
 9 files changed, 158 insertions(+)
---
diff --git a/src/backends/meta-backend.c b/src/backends/meta-backend.c
index 6d1c22e65..7feef3b0d 100644
--- a/src/backends/meta-backend.c
+++ b/src/backends/meta-backend.c
@@ -22,6 +22,22 @@
  *     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:
+ * - Monitor configuration (using an internal #MetaMonitorManager)
+ * - Modesetting (depending on the backend, this can be done either by X or KMS)
+ * - Input device configuration
+ * - Setting the hardware cursor sprite (using #MetaCursorTracker)
+ * - Interacting with logind
+ * - ... and much more
+ *
+ * Note that the #MetaBackend is completely unrelated to #ClutterBackend.
+ */
+
 #include "config.h"
 
 #include <stdlib.h>
@@ -1117,6 +1133,14 @@ 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. If @constraint is %NULL, the current
+ * one is removed
+ */
 void
 meta_backend_set_client_pointer_constraint (MetaBackend           *backend,
                                             MetaPointerConstraint *constraint)
@@ -1239,6 +1263,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 1c6871f58..4ec712e3e 100644
--- a/src/backends/meta-cursor-tracker.c
+++ b/src/backends/meta-cursor-tracker.c
@@ -312,6 +312,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 #CursorTracker 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..965d721a4 100644
--- a/src/backends/meta-logical-monitor.c
+++ b/src/backends/meta-logical-monitor.c
@@ -19,6 +19,21 @@
  * 02111-1307, USA.
  */
 
+/**
+ * SECTION:meta-logical-monitor
+ * @title: MetaLogicalMonitor
+ * @short_description: An abstraction for a monitor(set) and its configuration.
+ *
+ * A MetaLogicalMonitor represents a single "logical" monitor: a single
+ * viewport, with its own transformations (e.g. scaling). It can consist of one
+ * ore more #MetaMonitor<!-- -->s; the latter can happen for example when 2
+ * monitors are mirrored.
+ *
+ * The abstracion of the MetaLogicalMonitor allows us to abstract away the
+ * specifics of the monitors' setup. It can then be used in a relatively easy
+ * way in e.g. #MetaRendererView.
+ */
+
 #include "config.h"
 
 #include "backends/meta-logical-monitor.h"
diff --git a/src/backends/meta-pointer-constraint.c b/src/backends/meta-pointer-constraint.c
index 40ee3d32f..cb1787224 100644
--- a/src/backends/meta-pointer-constraint.c
+++ b/src/backends/meta-pointer-constraint.c
@@ -22,6 +22,25 @@
  *     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.
+ */
+
+/**
+ * MetaPointerConstraintClass:
+ * @constrain: the virtual function pointer for
+ *             meta_pointer_constraint_constrain().
+ */
+
 #include "config.h"
 
 #include "backends/meta-pointer-constraint.h"
@@ -40,6 +59,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-renderer-view.c b/src/backends/meta-renderer-view.c
index 19ab9efc8..6c6014434 100644
--- a/src/backends/meta-renderer-view.c
+++ b/src/backends/meta-renderer-view.c
@@ -15,6 +15,18 @@
  * 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.
+ */
+
 #include "config.h"
 
 #include "backends/meta-renderer-view.h"
diff --git a/src/backends/meta-renderer.c b/src/backends/meta-renderer.c
index ceac7df57..4c92ace04 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 <glib-object.h>
@@ -50,6 +62,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)
 {
@@ -86,6 +105,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 379e09d5a..2f57661cc 100644
--- a/src/backends/native/meta-clutter-backend-native.c
+++ b/src/backends/native/meta-clutter-backend-native.c
@@ -22,6 +22,17 @@
  *     Jonas Ådahl <jadahl gmail com>
  */
 
+/**
+ * SECTION:meta-clutter-backend-native
+ * @title: MetaClutterBackendNatve
+ * @short_description: A native backend which renders using EGL.
+ *
+ * MetaClutterBackendNative is a "native" #ClutterBackend, which means it will
+ * render its stage(views) using #CoglRenderer<!-- -->s.
+ *
+ * Note that MetaClutterBackendNative is something different than e #MetBackend.
+ */
+
 #include "config.h"
 
 #include <glib-object.h>
diff --git a/src/wayland/meta-pointer-confinement-wayland.c b/src/wayland/meta-pointer-confinement-wayland.c
index 1e95c1f0d..516c80216 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"