From 5f4fa18779fca83da7f13723a26723766e2f2589 Mon Sep 17 00:00:00 2001 From: Fabio Fantoni Date: Sun, 6 Oct 2024 08:40:22 -0400 Subject: [PATCH] gir: Correct usage of the closure annotation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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/-/merge_requests/4058 --- clutter/clutter/clutter-actor.c | 4 ++-- clutter/clutter/clutter-timeline.c | 4 ++-- cogl/cogl/cogl-onscreen.h | 12 ++++++------ cogl/cogl/cogl-pipeline.h | 4 ++-- src/tests/clutter-test-utils.c | 4 ++-- 5 files changed, 14 insertions(+), 14 deletions(-) diff --git a/clutter/clutter/clutter-actor.c b/clutter/clutter/clutter-actor.c index 69e78a52a..b5f333867 100644 --- a/clutter/clutter/clutter-actor.c +++ b/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. * diff --git a/clutter/clutter/clutter-timeline.c b/clutter/clutter/clutter-timeline.c index b6f7ac666..acd4784f3 100644 --- a/clutter/clutter/clutter-timeline.c +++ b/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 * diff --git a/cogl/cogl/cogl-onscreen.h b/cogl/cogl/cogl-onscreen.h index 40bd6780b..a7b50e2af 100644 --- a/cogl/cogl/cogl-onscreen.h +++ b/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. * diff --git a/cogl/cogl/cogl-pipeline.h b/cogl/cogl/cogl-pipeline.h index 16acc772d..a7828dc27 100644 --- a/cogl/cogl/cogl-pipeline.h +++ b/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. diff --git a/src/tests/clutter-test-utils.c b/src/tests/clutter-test-utils.c index 59db1021a..bebb6293d 100644 --- a/src/tests/clutter-test-utils.c +++ b/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.