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

[Jonas Ådahl <jadahl src gnome org>]

commit ca5f3098220ef639fdbca5c5b0b785afbc3e61fd
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 | 29 +++++++++++++++++++++++++++++
 clutter/clutter/clutter-stage.h |  6 +++---
 2 files changed, 32 insertions(+), 3 deletions(-)
---
diff --git a/clutter/clutter/clutter-stage.c b/clutter/clutter/clutter-stage.c
index c3c20936d4..3808d29559 100644
--- a/clutter/clutter/clutter-stage.c
+++ b/clutter/clutter/clutter-stage.c
@@ -3223,6 +3223,20 @@ 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 size of the framebuffer one must pass to
+ * clutter_stage_paint_to_buffer() or clutter_stage_paint_to_framebuffer()
+ * would be used with the same @rect.
+ *
+ * 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 +3334,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,
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,