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

[Niels De Graef <nielsdg src gnome org>]

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

    WIP: add some gtk-doc comments.

 src/backends/meta-backend.c                       | 24 +++++++++++++++++++
 src/backends/meta-logical-monitor.c               | 15 ++++++++++++
 src/backends/meta-renderer-view.c                 | 12 ++++++++++
 src/backends/meta-renderer.c                      | 29 +++++++++++++++++++++++
 src/backends/native/meta-clutter-backend-native.c | 11 +++++++++
 5 files changed, 91 insertions(+)
---
diff --git a/src/backends/meta-backend.c b/src/backends/meta-backend.c
index 6d1c22e65..5611fea2d 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: MetBackend
+ * @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
+ * - Interaction with logind
+ * - ... and much more
+ *
+ * Note that the #MetaBackend is completely unrelated to #ClutterBackend.
+ */
+
 #include "config.h"
 
 #include <stdlib.h>
@@ -1239,6 +1255,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-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-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>