[mutter/wip/tintou/clutter-stage-docs] clutter/stage: Add documentation and annotations

[Corentin Noël <corentinnoel src gnome org>]

commit d48027fd5d159312c3e389f60518688e39d1ea1c
Author: Corentin Noël <corentin noel collabora com>
Date:   Mon Nov 2 10:13:22 2020 +0100

    clutter/stage: Add documentation and annotations
    
    Increase the documentation coverage and add some missing annotations to be able to
    use some methods correctly with the GObject Introspection.

 clutter/clutter/clutter-stage.c | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)
---
diff --git a/clutter/clutter/clutter-stage.c b/clutter/clutter/clutter-stage.c
index c3c20936d4..a5653818e5 100644
--- a/clutter/clutter/clutter-stage.c
+++ b/clutter/clutter/clutter-stage.c
@@ -3223,6 +3223,18 @@ clutter_stage_presented (ClutterStage     *stage,
   g_signal_emit (stage, stage_signals[PRESENTED], 0, view, frame_info);
 }
 
+/**
+ * clutter_stage_get_capture_final_size:
+ * @stage: a #ClutterStage actor
+ * @rect: a #cairo_rectangle_int_t
+ * @out_width: (out) (optional): the final width
+ * @out_height: (out) (optional): the final height
+ * @out_scale: (out) (optional): the final scale factor
+ *
+ * Get the final size of the provided stage
+ *
+ * Returns: %TRUE if the size has been retrieved, %FALSE otherwise.
+ */
 gboolean
 clutter_stage_get_capture_final_size (ClutterStage          *stage,
                                       cairo_rectangle_int_t *rect,
@@ -3320,6 +3332,21 @@ clutter_stage_paint_to_framebuffer (ClutterStage                *stage,
   clutter_paint_context_destroy (paint_context);
 }
 
+/**
+ * clutter_stage_paint_to_buffer:
+ * @stage: a #ClutterStage actor
+ * @rect: a #cairo_rectangle_int_t
+ * @scale: the scale
+ * @data: (inout) (array) (element-type guint8): a pointer to the data
+ * @stride: stride of the image surface
+ * @format: the pixel format
+ * @paint_flags: the #ClutterPaintFlag
+ * @error: the error
+ *
+ * Take a snapshot of the stage to a provided buffer.
+ *
+ * Returns: %TRUE is the buffer has been paint successfully, %FALSE otherwise.
+ */
 gboolean
 clutter_stage_paint_to_buffer (ClutterStage                 *stage,
                                const cairo_rectangle_int_t  *rect,
@@ -3434,6 +3461,15 @@ capture_view_into (ClutterStage          *stage,
   cogl_object_unref (bitmap);
 }
 
+/**
+ * clutter_stage_capture_into:
+ * @stage: a #ClutterStage actor
+ * @paint: %TRUE to ensure that the stage has been painted
+ * @rect: a #cairo_rectangle_int_t
+ * @data: (inout) (array) (element-type guint8): a pointer to the data
+ *
+ * Take a capture of the stage to a provided buffer.
+ */
 void
 clutter_stage_capture_into (ClutterStage          *stage,
                             gboolean               paint,