gir: Correct usage of the closure annotation (#704)

Whenever you’re describing a function that takes a callback, you
should always annotate the callback argument with the argument that
contains the user data using the (closure argument) annotation

You should not annotate the data argument with a unary (closure).

The unary (closure) is meant to be used when annotating the callback
type

Ref:
https://gitlab.gnome.org/GNOME/mutter/-/commit/077eb80a8d9bb2968c2bfac959c2f2ca966ca7e7

Co-authored-by: Fabio Fantoni <[email protected]>

clutter/clutter/clutter-actor.c

@@ -13069,8 +13069,8 @@ typedef enum
  * @self: a #ClutterActor
  * @child: a #ClutterActor
  * @flags: control flags for actions
- * @add_func: delegate function
- * @data: (closure): data to pass to @add_func
+ * @add_func (closure data): delegate function
+ * @data: data to pass to @add_func
  *
  * Adds @child to the list of children of @self.
  *

clutter/clutter/clutter-timeline.c

@@ -2184,8 +2184,8 @@ clutter_timeline_get_repeat_count (ClutterTimeline *timeline)
 /**
  * clutter_timeline_set_progress_func:
  * @timeline: a #ClutterTimeline
- * @func: (scope notified) (allow-none): a progress function, or %NULL
- * @data: (closure): data to pass to @func
+ * @func: (scope notified) (allow-none) (closure data): a progress function, or %NULL
+ * @data: data to pass to @func
  * @notify: a function to be called when the progress function is removed
  *    or the timeline is disposed
  *

cogl/cogl/cogl-onscreen.h

@@ -395,8 +395,8 @@ GType cogl_frame_closure_get_gtype (void);
 /**
  * cogl_onscreen_add_frame_callback:
  * @onscreen: A #CoglOnscreen framebuffer
- * @callback: (scope notified): A callback function to call for frame events
- * @user_data: (closure): A private pointer to be passed to @callback
+ * @callback: (scope notified) (closure user_data): A callback function to call for frame events
+ * @user_data: A private pointer to be passed to @callback
  * @destroy: (allow-none): An optional callback to destroy @user_data
  *           when the @callback is removed or @onscreen is freed.
  *
@@ -568,9 +568,9 @@ GType cogl_onscreen_resize_closure_get_gtype (void);
 /**
  * cogl_onscreen_add_resize_callback:
  * @onscreen: A #CoglOnscreen framebuffer
- * @callback: (scope notified): A #CoglOnscreenResizeCallback to call when
+ * @callback: (scope notified) (closure user_data): A #CoglOnscreenResizeCallback to call when
  *            the @onscreen changes size.
- * @user_data: (closure): Private data to be passed to @callback.
+ * @user_data: Private data to be passed to @callback.
  * @destroy: (allow-none): An optional callback to destroy @user_data
  *           when the @callback is removed or @onscreen is freed.
  *
@@ -683,8 +683,8 @@ GType cogl_onscreen_dirty_closure_get_gtype (void);
 /**
  * cogl_onscreen_add_dirty_callback:
  * @onscreen: A #CoglOnscreen framebuffer
- * @callback: (scope notified): A callback function to call for dirty events
- * @user_data: (closure): A private pointer to be passed to @callback
+ * @callback: (scope notified) (closure user_data): A callback function to call for dirty events
+ * @user_data: A private pointer to be passed to @callback
  * @destroy: (allow-none): An optional callback to destroy @user_data when the
  *           @callback is removed or @onscreen is freed.
  *

cogl/cogl/cogl-pipeline.h

@@ -142,9 +142,9 @@ typedef gboolean (*CoglPipelineLayerCallback) (CoglPipeline *pipeline,
 /**
  * cogl_pipeline_foreach_layer:
  * @pipeline: A #CoglPipeline object
- * @callback: (scope call): A #CoglPipelineLayerCallback to be
+ * @callback: (scope call) (closure user_data): A #CoglPipelineLayerCallback to be
  *            called for each layer index
- * @user_data: (closure): Private data that will be passed to the
+ * @user_data: Private data that will be passed to the
  *             callback
  *
  * Iterates all the layer indices of the given @pipeline.

src/tests/clutter-test-utils.c

@@ -199,8 +199,8 @@ clutter_test_add_data (const char    *test_path,
 /**
  * clutter_test_add_data_full:
  * @test_path: unique path for identifying the test
- * @test_func: (scope notified): function containing the test
- * @test_data: (closure): data to pass to the test function
+ * @test_func: (scope notified) (closure test_data): function containing the test
+ * @test_data: data to pass to the test function
  * @test_notify: function called when the test function ends
  *
  * Adds a test unit to the Clutter test environment.