[mutter/bilelmoussaoui/clutter-docs: 2/3] cally: Migrate to gi-docgen

[Marge Bot <marge-bot src gnome org>]

commit 7b7e1c6fbd7d7ab5574920166e819b53af77e468
Author: Bilal Elmoussaoui <belmouss redhat com>
Date:   Tue May 31 10:29:15 2022 +0200

    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: <https://gitlab.gnome.org/GNOME/mutter/-/merge_requests/2441>

 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 bc7c3fa8fe..0570d93b4d 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 ebf096262a..929150d750 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 <structname>CallyActor</structname> 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 f1832a50dc..66ea0a50a8 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 24b0def861..e2dbac0ef6 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 <structname>CallyClone</structname> 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 34473fcd75..2c2746e3d6 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 16bba36efd..43a6fc76be 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 <structname>CallyRoot</structname> 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 c00ada46ec..fd9636a012 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 576ba6b81d..aeb1aa8f5a 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 <structname>CallyStage</structname> 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 fe4abb710c..f3454c6cb1 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 070ac9139c..b4d1547a4e 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 <structname>CallyText</structname> 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 5332951006..e40c3b4322 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 5556d40cfb..7ec36928ac 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 <structname>CallyUtil</structname> structure contains only
- * private data and should be accessed using the provided API
- *
- * Since: 1.4
- */
 struct _CallyUtil
 {
   /*< private >*/