From 25bb5676df2a0458e3088c653991b1abc4b49174 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Corentin=20No=C3=ABl?= <corentin.noel@collabora.com>
Date: Mon, 2 Nov 2020 10:13:22 +0100
Subject: [PATCH] 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.

Part-of: <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 c3c20936d..3808d2955 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 7d94b68c3..59a4ad145 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,