[gtk/wip/ottie/print: 87/90] Add some docs

[Matthias Clasen <matthiasc src gnome org>]

commit 2c073e684c239ceada0552b88d4aded63d33c31e
Author: Matthias Clasen <mclasen redhat com>
Date:   Sun Dec 27 12:02:17 2020 -0500

    Add some docs
    
    Document some of the high-level structure of ottie.

 ottie/ottiecomposition.c | 10 ++++++++++
 ottie/ottiecreation.c    | 14 ++++++++++++++
 ottie/ottielayer.c       | 12 ++++++++++++
 ottie/ottieobject.c      |  9 +++++++++
 ottie/ottiepaintable.c   | 13 +++++++++++++
 ottie/ottieplayer.c      |  8 ++++++++
 ottie/ottierender.c      |  6 ++++++
 ottie/ottieshape.c       | 19 +++++++++++++++++++
 8 files changed, 91 insertions(+)
---
diff --git a/ottie/ottiecomposition.c b/ottie/ottiecomposition.c
index 0f09e861db..2999451826 100644
--- a/ottie/ottiecomposition.c
+++ b/ottie/ottiecomposition.c
@@ -29,6 +29,16 @@
 #include <glib/gi18n-lib.h>
 #include <gsk/gsk.h>
 
+/*
+ * An OttieComposition is an OttieLayer that contains
+ * an array of other layers. It is created by calling
+ * ottie_composition_parse_layers() with a JsonReader
+ * object while parsing a Lottie animation.
+ *
+ * For ease of manipulation, OttieComposition implements
+ * the GListModel interface.
+ */
+
 #define GDK_ARRAY_ELEMENT_TYPE OttieLayer *
 #define GDK_ARRAY_FREE_FUNC g_object_unref
 #define GDK_ARRAY_TYPE_NAME OttieLayerList
diff --git a/ottie/ottiecreation.c b/ottie/ottiecreation.c
index 1aaa4ff70d..94351a275a 100644
--- a/ottie/ottiecreation.c
+++ b/ottie/ottiecreation.c
@@ -28,6 +28,20 @@
 #include <glib/gi18n-lib.h>
 #include <json-glib/json-glib.h>
 
+/**
+ * SECTION:ottiecreation
+ * @Title: Creation
+ * @Short_description: Top-level object for Lottie animations
+ *
+ * OttieCreation is the top-level object which holds a Lottie
+ * animation. You can create an OttieCreation by loading a Lottie
+ * file with otte_creation_new_for_file() or ottie_creation_load_file(),
+ * or by parsing a Lottie animation from memory with ottie_creation_load_bytes().
+ *
+ * OttieCreation provides some general information about the loaded
+ * animation, such as a name, the frame rate, start and end frames
+ * and the dimensions.
+ */
 struct _OttieCreation
 {
   GObject parent;
diff --git a/ottie/ottielayer.c b/ottie/ottielayer.c
index 1ff294afd2..df13a08d6e 100644
--- a/ottie/ottielayer.c
+++ b/ottie/ottielayer.c
@@ -24,6 +24,18 @@
 #include <glib/gi18n-lib.h>
 #include <json-glib/json-glib.h>
 
+/*
+ * OttieLayer is the parent class for all kinds of layers
+ * in Lottie animations.
+ *
+ * OttieComposition - a layer that contains other layers
+ * OttieShapeLayer - a layer containing shapes
+ * OttieNullLayer - a layer that does nothing
+ *
+ * Layers are organized in a tree (via composition layers),
+ * and rendering an animation is just rendering all its layers.
+ */
+
 G_DEFINE_TYPE (OttieLayer, ottie_layer, OTTIE_TYPE_OBJECT)
 
 static void
diff --git a/ottie/ottieobject.c b/ottie/ottieobject.c
index 5720555b77..101464f4af 100644
--- a/ottie/ottieobject.c
+++ b/ottie/ottieobject.c
@@ -23,6 +23,15 @@
 
 #include "ottieintl.h"
 
+/*
+ * OttieObject is the base class for all objects that are
+ * created by parsing a Lottie animation. Every such object
+ * has a name and a match-name. The match-name is used for
+ * referencing the object in scripts.
+ *
+ * The two subclasses of OttieObject are OttieLayer and OttieShape.
+ */
+
 enum {
   PROP_0,
   PROP_MATCH_NAME,
diff --git a/ottie/ottiepaintable.c b/ottie/ottiepaintable.c
index bb0a4e578b..620c393bd0 100644
--- a/ottie/ottiepaintable.c
+++ b/ottie/ottiepaintable.c
@@ -26,6 +26,19 @@
 #include <math.h>
 #include <glib/gi18n.h>
 
+/**
+ * SECTION:ottiepaintable
+ * @Title: Paintable
+ * @Short_description: GdkPaintable implementation for Lottie
+ *
+ * OttiePaintable is an implementation of GdkPaintable that can
+ * draw Lottie animations. To create an OttiePaintable, you need
+ * a OttieCreation (i.e. a parsed Lottie animation).
+ *
+ * Beyond the standard GdkPaintable API, OttiePaintable lets you
+ * get and set the current timestamp, and query to overall duration
+ * of the animation.
+ */
 struct _OttiePaintable
 {
   GObject parent_instance;
diff --git a/ottie/ottieplayer.c b/ottie/ottieplayer.c
index d41aa5e2a3..92d3e011f5 100644
--- a/ottie/ottieplayer.c
+++ b/ottie/ottieplayer.c
@@ -26,6 +26,14 @@
 
 #include <glib/gi18n.h>
 
+/**
+ * SECTION:ottieplayer
+ * @Title: Player
+ * @Short_description: Plays a Lottie animation
+ *
+ * OttiePlayer is an implementation of the GtkMediaStream interface
+ * for Lottie animations.
+ */
 struct _OttiePlayer
 {
   GObject parent_instance;
diff --git a/ottie/ottierender.c b/ottie/ottierender.c
index 4f9ecb2e51..daa764a1be 100644
--- a/ottie/ottierender.c
+++ b/ottie/ottierender.c
@@ -23,6 +23,12 @@
 
 #include "ottierenderobserverprivate.h"
 
+/*
+ * OttieRender is the renderer object that is used for
+ * turning a Lottie animation plus a timestamp into a
+ * render node. It handles caching for expensive parts
+ * of the rendering, such as paths.
+ */
 void
 ottie_render_init (OttieRender         *self,
                    OttieRenderObserver *observer)
diff --git a/ottie/ottieshape.c b/ottie/ottieshape.c
index 9832680c87..fdfb6b922a 100644
--- a/ottie/ottieshape.c
+++ b/ottie/ottieshape.c
@@ -23,6 +23,25 @@
 
 #include <glib/gi18n-lib.h>
 
+/*
+ * OttieShape is the base class of all shape objects in
+ * Lottie animations. Shapes are operations that are applied
+ * to the render tree, for example:
+ *
+ * - adding a rectangle to the list of paths
+ * - trimming or offsetting an existing path
+ * - rendering a path by stroking or filling it
+ *
+ * There are many subclasses of OttieShape:
+ *
+ * - OttieEllipseShape
+ * - OttieRectShape
+ * - OttiePathShape
+ * - OttieFillShape
+ * - OttieStrokeShape
+ * - OttieTrimShape
+ * - OttieGroupShape
+ */
 G_DEFINE_TYPE (OttieShape, ottie_shape, OTTIE_TYPE_OBJECT)
 
 static void