[gtk+] gsk: Documentation additions

[Matthias Clasen <matthiasc src gnome org>]

commit f6626a9e0eaafdce8913bdc1b45e9e64d0909ab6
Author: Matthias Clasen <mclasen redhat com>
Date:   Sun Sep 24 21:53:54 2017 -0400

    gsk: Documentation additions
    
    Document newly added apis, and ensure that all public apis
    are listed in the docs.

 docs/reference/gsk/gsk4-sections.txt |    5 ++
 gsk/gskrenderer.c                    |   13 ++++++
 gsk/gskrendernode.c                  |   11 +++++
 gsk/gskrendernodeimpl.c              |   74 +++++++++++++++++++++++++++++-----
 gsk/gskroundedrect.c                 |    2 +-
 gsk/gsktexture.c                     |   33 +++++++++++++++-
 6 files changed, 125 insertions(+), 13 deletions(-)
---
diff --git a/docs/reference/gsk/gsk4-sections.txt b/docs/reference/gsk/gsk4-sections.txt
index a4498ca..925c694 100644
--- a/docs/reference/gsk/gsk4-sections.txt
+++ b/docs/reference/gsk/gsk4-sections.txt
@@ -56,6 +56,7 @@ gsk_transform_node_get_child
 gsk_opacity_node_new
 gsk_opacity_node_get_child
 gsk_color_matrix_node_new
+gsk_color_matrix_node_get_child
 gsk_repeat_node_new
 gsk_clip_node_new
 gsk_clip_node_get_child
@@ -66,6 +67,8 @@ gsk_shadow_node_new
 GskBlendMode
 gsk_blend_node_new
 gsk_cross_fade_node_new
+gsk_text_node_new
+gsk_blur_node_new
 <SUBSECTION Standard>
 GSK_IS_RENDER_NODE
 GSK_RENDER_NODE
@@ -84,6 +87,7 @@ GSK_TYPE_SERIALIZATION_ERROR
 <SECTION>
 <FILE>GskTexture</FILE>
 gsk_texture_new_for_data
+gsk_texture_new_for_surface
 gsk_texture_new_for_pixbuf
 gsk_texture_get_width
 gsk_texture_get_height
@@ -99,6 +103,7 @@ GSK_IS_TEXTURE
 <FILE>GskRoundedRect</FILE>
 GskCorner
 GskRoundedRect
+GSK_ROUNDED_RECT_INIT
 gsk_rounded_rect_init
 gsk_rounded_rect_init_copy
 gsk_rounded_rect_init_from_rect
diff --git a/gsk/gskrenderer.c b/gsk/gskrenderer.c
index 35747c9..3e45766 100644
--- a/gsk/gskrenderer.c
+++ b/gsk/gskrenderer.c
@@ -967,6 +967,19 @@ gsk_renderer_begin_draw_frame (GskRenderer          *renderer,
   return priv->drawing_context;
 }
 
+/**
+ * gsk_renderer_end_draw_frame:
+ * @renderer: a #GskRenderer
+ * @context: the drawing context returned by the matching call to
+ *     gsk_renderer_begin_draw_frame()
+ *
+ * Release the drawning context returned by gsk_renderer_begin_draw_frame().
+ *
+ * Calls to gsk_renderer_begin_draw_frame() and gsk_renderer_end_draw_frame()
+ * must be paired.
+ *
+ * Since: 3.90
+ */
 void
 gsk_renderer_end_draw_frame (GskRenderer       *renderer,
                              GdkDrawingContext *context)
diff --git a/gsk/gskrendernode.c b/gsk/gskrendernode.c
index 0954c5b..53a2363 100644
--- a/gsk/gskrendernode.c
+++ b/gsk/gskrendernode.c
@@ -181,6 +181,17 @@ gsk_render_node_get_bounds (GskRenderNode   *node,
   graphene_rect_init_from_rect (bounds, &node->bounds);
 }
 
+/**
+ * gsk_render_node_set_scaling_filters:
+ * @node: a #GskRenderNode
+ * @min_filter: the filter for scaling down
+ * @mag_filter: the filter for scaling up
+ *
+ * Sets filters to be used when a node must be scaled up
+ * or down.
+ *
+ * Since: 3.90
+ */
 void
 gsk_render_node_set_scaling_filters (GskRenderNode    *node,
                                      GskScalingFilter  min_filter,
diff --git a/gsk/gskrendernodeimpl.c b/gsk/gskrendernodeimpl.c
index c5d26b2..3dcd1cb 100644
--- a/gsk/gskrendernodeimpl.c
+++ b/gsk/gskrendernodeimpl.c
@@ -333,10 +333,7 @@ gsk_linear_gradient_node_new (const graphene_rect_t  *bounds,
   g_return_val_if_fail (n_color_stops >= 2, NULL);
   g_return_val_if_fail (color_stops[0].offset >= 0, NULL);
   for (i = 1; i < n_color_stops; i++)
-    {
-      g_return_val_if_fail (color_stops[i].offset >= color_stops[i-1].offset, NULL);
-
-    }
+    g_return_val_if_fail (color_stops[i].offset >= color_stops[i-1].offset, NULL);
   g_return_val_if_fail (color_stops[n_color_stops - 1].offset <= 1, NULL);
 
   self = (GskLinearGradientNode *) gsk_render_node_new (&GSK_LINEAR_GRADIENT_NODE_CLASS, sizeof 
(GskColorStop) * n_color_stops);
@@ -351,6 +348,22 @@ gsk_linear_gradient_node_new (const graphene_rect_t  *bounds,
   return &self->render_node;
 }
 
+/**
+ * gsk_repeating_linear_gradient_node_new:
+ * @bounds: the rectangle to render the linear gradient into
+ * @start: the point at which the linear gradient will begin
+ * @end: the point at which the linear gradient will finish
+ * @color_stops: a pointer to an array of #GskColorStop defining the gradient
+ * @n_color_stops: the number of elements in @color_stops
+ *
+ * Creates a #GskRenderNode that will create a repeating linear gradient
+ * from the given points and color stops, and render that into the area
+ * given by @bounds.
+ *
+ * Returns: A new #GskRenderNode
+ *
+ * Since: 3.90
+ */
 GskRenderNode *
 gsk_repeating_linear_gradient_node_new (const graphene_rect_t  *bounds,
                                         const graphene_point_t *start,
@@ -368,10 +381,7 @@ gsk_repeating_linear_gradient_node_new (const graphene_rect_t  *bounds,
   g_return_val_if_fail (n_color_stops >= 2, NULL);
   g_return_val_if_fail (color_stops[0].offset >= 0, NULL);
   for (i = 1; i < n_color_stops; i++)
-    {
-      g_return_val_if_fail (color_stops[i].offset >= color_stops[i-1].offset, NULL);
-
-    }
+    g_return_val_if_fail (color_stops[i].offset >= color_stops[i-1].offset, NULL);
   g_return_val_if_fail (color_stops[n_color_stops - 1].offset <= 1, NULL);
 
   self = (GskLinearGradientNode *) gsk_render_node_new (&GSK_REPEATING_LINEAR_GRADIENT_NODE_CLASS, sizeof 
(GskColorStop) * n_color_stops);
@@ -2112,6 +2122,17 @@ gsk_container_node_get_n_children (GskRenderNode *node)
   return container->n_children;
 }
 
+/**
+ * gsk_container_node_get_child:
+ * @node: a container #GskRenderNode
+ * @idx: the position of the child to get
+ *
+ * Gets one of the children of @container.
+ *
+ * Returns: the @idx'th child of @container
+ *
+ * Since: 3.90
+ */
 GskRenderNode *
 gsk_container_node_get_child (GskRenderNode *node,
                               guint          idx)
@@ -2221,7 +2242,7 @@ gsk_transform_node_deserialize (GVariant  *variant,
                                        mat[8], mat[9], mat[10], mat[11],
                                        mat[12], mat[13], mat[14], mat[15]
                                    });
-                                    
+
   result = gsk_transform_node_new (child, &transform);
 
   gsk_render_node_unref (child);
@@ -2614,7 +2635,7 @@ gsk_color_matrix_node_deserialize (GVariant  *variant,
                                        mat[12], mat[13], mat[14], mat[15]
                                    });
   graphene_vec4_init (&offset, vec[0], vec[1], vec[2], vec[3]);
-                                    
+
   result = gsk_color_matrix_node_new (child, &matrix, &offset);
 
   gsk_render_node_unref (child);
@@ -2641,7 +2662,7 @@ static const GskRenderNodeClass GSK_COLOR_MATRIX_NODE_CLASS = {
  * Creates a #GskRenderNode that will drawn the @child with reduced
  * @color_matrix.
  *
- * In particular, the node will transform the operation  
+ * In particular, the node will transform the operation
  *   pixel = color_matrix * pixel + color_offset
  * for every pixel.
  *
@@ -2669,6 +2690,14 @@ gsk_color_matrix_node_new (GskRenderNode           *child,
   return &self->render_node;
 }
 
+/**
+ * gsk_color_matrix_node_get_child:
+ * @node: a color matrix @GskRenderNode
+ *
+ * Gets the child node that is getting its colors modified by the given @node.
+ *
+ * Returns: (transfer none): The child that is getting its colors modified
+ **/
 GskRenderNode *
 gsk_color_matrix_node_get_child (GskRenderNode *node)
 {
@@ -3994,6 +4023,20 @@ static const GskRenderNodeClass GSK_TEXT_NODE_CLASS = {
   gsk_text_node_deserialize
 };
 
+/**
+ * gsk_text_node_new:
+ * @font: the #PangoFont containing the glyphs
+ * @glyphs: the #PangoGlyphString to render
+ * @color: the foreground color to render with
+ * @x: the x coordinate at which to put the baseline
+ * @y: the y coordinate at wihch to put the baseline
+ *
+ * Creates a render node that renders the given glyphs,
+ * Note that @color may not be used if the font contains
+ * color glyphs.
+ *
+ * Since: 3.92
+ */
 GskRenderNode *
 gsk_text_node_new (PangoFont        *font,
                    PangoGlyphString *glyphs,
@@ -4322,6 +4365,15 @@ static const GskRenderNodeClass GSK_BLUR_NODE_CLASS = {
   gsk_blur_node_deserialize
 };
 
+/**
+ * gsk_blur_node_new:
+ * @child: the child node to blur
+ * @radius: the blur radius
+ *
+ * Creates a render node that blurs the child.
+ *
+ * Since: 3.92
+ */
 GskRenderNode *
 gsk_blur_node_new (GskRenderNode *child,
                    double         radius)
diff --git a/gsk/gskroundedrect.c b/gsk/gskroundedrect.c
index 75c4e5a..ce9757e 100644
--- a/gsk/gskroundedrect.c
+++ b/gsk/gskroundedrect.c
@@ -500,7 +500,7 @@ gsk_rounded_rect_path (const GskRoundedRect *self,
   cairo_close_path (cr);
 }
 
-/*
+/*< private >
  * Converts to the format we use in our shaders:
  * vec4 rect;
  * vec4 corner_widths;
diff --git a/gsk/gsktexture.c b/gsk/gsktexture.c
index f373aed..03691ff 100644
--- a/gsk/gsktexture.c
+++ b/gsk/gsktexture.c
@@ -22,6 +22,8 @@
  * @Short_description: Pixel data uploaded to a #GskRenderer
  *
  * #GskTexture is the basic element used to refer to pixel data.
+ * It is primarily mean for pixel data that will not change over
+ * multiple frames, and will be used for a long time.
  *
  * You cannot get your pixel data back once you've uploaded it.
  *
@@ -135,7 +137,7 @@ gsk_texture_get_property (GObject    *gobject,
 
 static void
 gsk_texture_dispose (GObject *object)
-{    
+{
   GskTexture *self = GSK_TEXTURE (object);
 
   gsk_texture_clear_render_data (self);
@@ -277,6 +279,18 @@ gsk_cairo_texture_init (GskCairoTexture *self)
 {
 }
 
+/**
+ * gsk_texture_new_for_data:
+ * @data: the pixel data
+ * @width: the number of pixels in each row
+ * @height: the number of rows
+ * @stride: the distance from the beginning of one row to the next, in bytes
+ *
+ * Creates a new texture object holding the given data.
+ * The data is assumed to be in CAIRO_FORMAT_ARGB32 format.
+ *
+ * Returns: a new #GskTexture
+ */
 GskTexture *
 gsk_texture_new_for_data (const guchar *data,
                           int           width,
@@ -304,6 +318,15 @@ gsk_texture_new_for_data (const guchar *data,
   return texture;
 }
 
+/**
+ * gsk_texture_new_for_surface:
+ * @surface: a cairo image surface
+ *
+ * Creates a new texture object representing the surface.
+ * @surface must be an image surface with format CAIRO_FORMAT_ARGB32.
+ *
+ * Returns: a new #GskTexture
+ */
 GskTexture *
 gsk_texture_new_for_surface (cairo_surface_t *surface)
 {
@@ -391,6 +414,14 @@ gsk_pixbuf_texture_init (GskPixbufTexture *self)
 {
 }
 
+/**
+ * gsk_texture_new_for_pixbuf:
+ * @pixbuf: a #GdkPixbuf
+ *
+ * Creates a new texture object representing the GdkPixbuf.
+ *
+ * Returns: a new #GskTexture
+ */
 GskTexture *
 gsk_texture_new_for_pixbuf (GdkPixbuf *pixbuf)
 {