From 7b7e1c6fbd7d7ab5574920166e819b53af77e468 Mon Sep 17 00:00:00 2001 From: Bilal Elmoussaoui Date: Tue, 31 May 2022 10:29:15 +0200 Subject: [PATCH] cally: Migrate to gi-docgen Similar to the clutter commits - Drop all the private structs documentations - Make use of gi-docgen items linking as much as possible - Use markdown formatting for code snippets Part-of: --- clutter/clutter/cally/cally-actor.c | 15 ++++++++------- clutter/clutter/cally/cally-actor.h | 14 ++++---------- clutter/clutter/cally/cally-clone.c | 13 +++++++------ clutter/clutter/cally/cally-clone.h | 8 -------- clutter/clutter/cally/cally-root.c | 16 +++++++++------- clutter/clutter/cally/cally-root.h | 8 -------- clutter/clutter/cally/cally-stage.c | 17 +++++++++-------- clutter/clutter/cally/cally-stage.h | 8 -------- clutter/clutter/cally/cally-text.c | 12 ++++++------ clutter/clutter/cally/cally-text.h | 8 -------- clutter/clutter/cally/cally-util.c | 9 +++++---- clutter/clutter/cally/cally-util.h | 8 -------- 12 files changed, 48 insertions(+), 88 deletions(-) diff --git a/clutter/clutter/cally/cally-actor.c b/clutter/clutter/cally/cally-actor.c index bc7c3fa8f..0570d93b4 100644 --- a/clutter/clutter/cally/cally-actor.c +++ b/clutter/clutter/cally/cally-actor.c @@ -23,13 +23,14 @@ */ /** - * SECTION:cally-actor - * @Title: CallyActor - * @short_description: Implementation of the ATK interfaces for #ClutterActor - * @see_also: #ClutterActor + * CallyActor: + * + * Implementation of the ATK interfaces for [class@Clutter.Actor] * - * #CallyActor implements the required ATK interfaces of #ClutterActor + * #CallyActor implements the required ATK interfaces of [class@Clutter.Actor] * exposing the common elements on each actor (position, extents, etc). + * + * Since: 1.4 */ /* @@ -1104,7 +1105,7 @@ cally_actor_add_action_full (CallyActor *cally_actor, * @cally_actor: a #CallyActor * @action_id: the action id * - * Removes a action, using the @action_id returned by cally_actor_add_action() + * Removes a action, using the @action_id returned by [method@Actor.add_action] * * Return value: %TRUE if the operation was successful, %FALSE otherwise * @@ -1138,7 +1139,7 @@ cally_actor_remove_action (CallyActor *cally_actor, * @action_name: the name of the action to remove * * Removes an action, using the @action_name used when the action was added - * with cally_actor_add_action() + * with [method@Actor.add_action] * * Return value: %TRUE if the operation was successful, %FALSE otherwise * diff --git a/clutter/clutter/cally/cally-actor.h b/clutter/clutter/cally/cally-actor.h index ebf096262..929150d75 100644 --- a/clutter/clutter/cally/cally-actor.h +++ b/clutter/clutter/cally/cally-actor.h @@ -62,22 +62,16 @@ typedef void (* CallyActionFunc) (CallyActor *cally_actor); * @user_data: user data passed to the function * * Action function, to be used on #AtkAction implementations as - * an individual action. Unlike #CallyActionFunc, this function - * uses the @user_data argument passed to cally_actor_add_action_full(). + * an individual action. + * + * Unlike #CallyActionFunc, this function uses the @user_data + * argument passed to [method@Actor.add_action_full]. * * Since: 1.6 */ typedef void (* CallyActionCallback) (CallyActor *cally_actor, gpointer user_data); -/** - * CallyActor: - * - * The CallyActor structure contains only private - * data and should be accessed using the provided API - * - * Since: 1.4 - */ struct _CallyActor { /*< private >*/ diff --git a/clutter/clutter/cally/cally-clone.c b/clutter/clutter/cally/cally-clone.c index f1832a50d..66ea0a50a 100644 --- a/clutter/clutter/cally/cally-clone.c +++ b/clutter/clutter/cally/cally-clone.c @@ -21,15 +21,16 @@ */ /** - * SECTION:cally-clone - * @Title: CallyClone - * @short_description: Implementation of the ATK interfaces for a #ClutterClone - * @see_also: #ClutterClone + * CallyClone: + * + * Implementation of the ATK interfaces for a #ClutterClone * - * #CallyClone implements the required ATK interfaces of #ClutterClone + * #CallyClone implements the required ATK interfaces of [class@Clutter.Clone] * * In particular it sets a proper role for the clone, as just a image, * as it is the sanest and simplest approach. + * + * Since: 1.4 */ /* Design rationale for CallyClone: @@ -100,7 +101,7 @@ cally_clone_init (CallyClone *clone) * @actor: a #ClutterActor * * Creates a new #CallyClone for the given @actor. @actor must be a - * #ClutterClone. + * [class@Clutter.Clone]. * * Return value: the newly created #AtkObject * diff --git a/clutter/clutter/cally/cally-clone.h b/clutter/clutter/cally/cally-clone.h index 24b0def86..e2dbac0ef 100644 --- a/clutter/clutter/cally/cally-clone.h +++ b/clutter/clutter/cally/cally-clone.h @@ -41,14 +41,6 @@ typedef struct _CallyClone CallyClone; typedef struct _CallyCloneClass CallyCloneClass; typedef struct _CallyClonePrivate CallyClonePrivate; -/** - * CallyClone: - * - * The CallyClone structure contains only private - * data and should be accessed using the provided API - * - * Since: 1.4 - */ struct _CallyClone { /*< private >*/ diff --git a/clutter/clutter/cally/cally-root.c b/clutter/clutter/cally/cally-root.c index 34473fcd7..2c2746e3d 100644 --- a/clutter/clutter/cally/cally-root.c +++ b/clutter/clutter/cally/cally-root.c @@ -21,18 +21,20 @@ */ /** - * SECTION:cally-root - * @short_description: Root object for the Cally toolkit - * @see_also: #ClutterStage + * CallyRoot: + * + * Root object for the Cally toolkit * * #CallyRoot is the root object of the accessibility tree-like * hierarchy, exposing the application level. * * Somewhat equivalent to #GailTopLevel. We consider that this class - * expose the a11y information of the #ClutterStageManager, as the - * children of this object are the different ClutterStage managed (so - * the #GObject used in the atk_object_initialize() is the - * #ClutterStageManager). + * expose the a11y information of the [class@Clutter.StageManager], as the + * children of this object are the different [class@Clutter.Stage] managed (so + * the [class@GObject.Object] used in the atk_object_initialize() is the + * [class@Clutter.StageManager]). + * + * Since: 1.4 */ #include "clutter-build-config.h" diff --git a/clutter/clutter/cally/cally-root.h b/clutter/clutter/cally/cally-root.h index 16bba36ef..43a6fc76b 100644 --- a/clutter/clutter/cally/cally-root.h +++ b/clutter/clutter/cally/cally-root.h @@ -41,14 +41,6 @@ typedef struct _CallyRoot CallyRoot; typedef struct _CallyRootClass CallyRootClass; typedef struct _CallyRootPrivate CallyRootPrivate; -/** - * CallyRoot: - * - * The CallyRoot structure contains only private - * data and should be accessed using the provided API - * - * Since: 1.4 - */ struct _CallyRoot { /*< private >*/ diff --git a/clutter/clutter/cally/cally-stage.c b/clutter/clutter/cally/cally-stage.c index c00ada46e..fd9636a01 100644 --- a/clutter/clutter/cally/cally-stage.c +++ b/clutter/clutter/cally/cally-stage.c @@ -21,18 +21,19 @@ */ /** - * SECTION:cally-stage - * @Title: CallyStage - * @short_description: Implementation of the ATK interfaces for a #ClutterStage - * @see_also: #ClutterStage + * CallyStage: + * + * Implementation of the ATK interfaces for a #ClutterStage * - * #CallyStage implements the required ATK interfaces for #ClutterStage + * #CallyStage implements the required ATK interfaces for [class@Clutter.Stage] * * Some implementation details: at this moment #CallyStage is used as * the most similar Window object in this toolkit (ie: emitting window - * related signals), although the real purpose of #ClutterStage is + * related signals), although the real purpose of [class@Clutter.Stage] is * being a canvas. Anyway, this is required for applications using - * just clutter, or directly #ClutterStage + * just clutter, or directly [class@Clutter.Stage] + * + * Since: 1.4 */ #include "clutter-build-config.h" @@ -93,7 +94,7 @@ cally_stage_init (CallyStage *cally_stage) * @actor: a #ClutterActor * * Creates a new #CallyStage for the given @actor. @actor should be a - * #ClutterStage. + * [class@Clutter.Stage]. * * Return value: the newly created #AtkObject * diff --git a/clutter/clutter/cally/cally-stage.h b/clutter/clutter/cally/cally-stage.h index 576ba6b81..aeb1aa8f5 100644 --- a/clutter/clutter/cally/cally-stage.h +++ b/clutter/clutter/cally/cally-stage.h @@ -41,14 +41,6 @@ typedef struct _CallyStage CallyStage; typedef struct _CallyStageClass CallyStageClass; typedef struct _CallyStagePrivate CallyStagePrivate; -/** - * CallyStage: - * - * The CallyStage structure contains only - * private data and should be accessed using the provided API - * - * Since: 1.4 - */ struct _CallyStage { /*< private >*/ diff --git a/clutter/clutter/cally/cally-text.c b/clutter/clutter/cally/cally-text.c index fe4abb710..f3454c6cb 100644 --- a/clutter/clutter/cally/cally-text.c +++ b/clutter/clutter/cally/cally-text.c @@ -29,14 +29,14 @@ */ /** - * SECTION:cally-text - * @short_description: Implementation of the ATK interfaces for a #ClutterText - * @see_also: #ClutterText + * CallyText: + * + * Implementation of the ATK interfaces for a [class@Clutter.Text] * * #CallyText implements the required ATK interfaces of - * #ClutterText, #AtkText and #AtkEditableText - * + * [class@Clutter.Text], #AtkText and #AtkEditableText * + * Since: 1.4 */ #include "clutter-build-config.h" @@ -257,7 +257,7 @@ cally_text_finalize (GObject *obj) * @actor: a #ClutterActor * * Creates a new #CallyText for the given @actor. @actor must be a - * #ClutterText. + * [class@Clutter.Text]. * * Return value: the newly created #AtkObject * diff --git a/clutter/clutter/cally/cally-text.h b/clutter/clutter/cally/cally-text.h index 070ac9139..b4d1547a4 100644 --- a/clutter/clutter/cally/cally-text.h +++ b/clutter/clutter/cally/cally-text.h @@ -41,14 +41,6 @@ typedef struct _CallyText CallyText; typedef struct _CallyTextClass CallyTextClass; typedef struct _CallyTextPrivate CallyTextPrivate; -/** - * CallyText: - * - * The CallyText structure contains only private - * data and should be accessed using the provided API - * - * Since: 1.4 - */ struct _CallyText { /*< private >*/ diff --git a/clutter/clutter/cally/cally-util.c b/clutter/clutter/cally/cally-util.c index 533295100..e40c3b432 100644 --- a/clutter/clutter/cally/cally-util.c +++ b/clutter/clutter/cally/cally-util.c @@ -24,10 +24,9 @@ */ /** - * SECTION:cally-util - * @Title: CallyUtil - * @short_description: #AtkUtil implementation - * @see_also: #ClutterActor + * CallyUtil: + * + * #AtkUtil implementation * * #CallyUtil implements #AtkUtil abstract methods. Although it * includes the name "Util" it is in fact one of the most important @@ -36,6 +35,8 @@ * For instance, it defines atk_get_root(), the method that returns * the root object in the hierarchy. Without it, you don't have * available any accessible object. + * + * Since: 1.4 */ #include "clutter-build-config.h" diff --git a/clutter/clutter/cally/cally-util.h b/clutter/clutter/cally/cally-util.h index 5556d40cf..7ec36928a 100644 --- a/clutter/clutter/cally/cally-util.h +++ b/clutter/clutter/cally/cally-util.h @@ -41,14 +41,6 @@ typedef struct _CallyUtil CallyUtil; typedef struct _CallyUtilClass CallyUtilClass; typedef struct _CallyUtilPrivate CallyUtilPrivate; -/** - * CallyUtil: - * - * The CallyUtil structure contains only - * private data and should be accessed using the provided API - * - * Since: 1.4 - */ struct _CallyUtil { /*< private >*/