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



commit 77f9c08999bff436a72f859a5c6bc762916bc551
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                       | 33 +++++++++++++++++++++++
 src/backends/meta-cursor-tracker.c                |  8 ++++++
 src/backends/meta-logical-monitor.c               | 19 +++++++++++++
 src/backends/meta-pointer-constraint.c            | 26 ++++++++++++++++++
 src/backends/meta-pointer-constraint.h            |  5 ++++
 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 +++++++
 10 files changed, 162 insertions(+)
---
diff --git a/src/backends/meta-backend.c b/src/backends/meta-backend.c
index 709d4194c..3e939f544 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 "backends/meta-backend-private.h"
@@ -1138,6 +1154,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 +1285,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..758cc89b3 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 #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..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-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..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 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..7b007759f 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 "backends/native/meta-clutter-backend-native.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"


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]