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>
This commit is contained in:
Bilal Elmoussaoui 2022-05-31 10:29:15 +02:00
parent c8e63866f0
commit 7b7e1c6fbd
12 changed files with 48 additions and 88 deletions

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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