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

@@ -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
  *

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 >*/

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
  *

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 >*/

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"

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 >*/

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
  *

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 >*/

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
  *

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 >*/

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"

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 >*/