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

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

commit fee063973026ec81094bd83e614835465276077c
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.
    
    https://gitlab.gnome.org/GNOME/mutter/-/merge_requests/1545

 clutter/clutter/clutter-stage.c | 36 ++++++++++++++++++++++++++++++++++++
 clutter/clutter/clutter-stage.h |  6 +++---
 2 files changed, 39 insertions(+), 3 deletions(-)
---
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,
diff --git a/clutter/clutter/clutter-stage.h b/clutter/clutter/clutter-stage.h
index 7d94b68c38..59a4ad145a 100644
--- a/clutter/clutter/clutter-stage.h
+++ b/clutter/clutter/clutter-stage.h
@@ -210,9 +210,9 @@ void clutter_stage_schedule_update (ClutterStage *stage);
 CLUTTER_EXPORT
 gboolean clutter_stage_get_capture_final_size (ClutterStage          *stage,
                                                cairo_rectangle_int_t *rect,
-                                               int                   *width,
-                                               int                   *height,
-                                               float                 *scale);
+                                               int                   *out_width,
+                                               int                   *out_height,
+                                               float                 *out_scale);
 
 CLUTTER_EXPORT
 void clutter_stage_paint_to_framebuffer (ClutterStage                *stage,