From a63eb10855a94426ecd53cc9888f08b1ced1cede Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Mon, 5 Jul 2010 15:10:42 +0100 Subject: [PATCH] docs: Fix Cally documentation --- clutter/cally/cally-actor.c | 64 +++++++++++++++++++-------------- clutter/cally/cally-clone.c | 43 ++++++++++++++++++++-- clutter/cally/cally-group.c | 19 ++++++++-- clutter/cally/cally-rectangle.c | 4 +-- clutter/cally/cally-root.c | 11 +++--- clutter/cally/cally-stage.c | 5 +-- clutter/cally/cally-text.c | 4 +-- clutter/cally/cally-texture.c | 5 +-- 8 files changed, 109 insertions(+), 46 deletions(-) diff --git a/clutter/cally/cally-actor.c b/clutter/cally/cally-actor.c index 379c9b995..41bd368a1 100644 --- a/clutter/cally/cally-actor.c +++ b/clutter/cally/cally-actor.c @@ -29,7 +29,7 @@ * @see_also: #ClutterActor * * #CallyActor implements the required ATK interfaces of #ClutterActor - * exposing the common elements on each ClutterActor (position, extents, etc). + * exposing the common elements on each actor (position, extents, etc). */ /* @@ -114,7 +114,7 @@ typedef struct _CallyActorActionInfo CallyActorActionInfo; -/** +/*< private > * CallyActorActionInfo: * @name: name of the action * @description: description of the action @@ -238,8 +238,17 @@ struct _CallyActorPrivate GList *children; }; - -AtkObject* +/** + * cally_actor_new: + * @actor: a #ClutterActor + * + * Creates a new #CallyActor for the given @actor + * + * Return value: the newly created #CallyActor + * + * Since: 1.4 + */ +AtkObject * cally_actor_new (ClutterActor *actor) { gpointer object; @@ -889,7 +898,7 @@ _is_actor_on_screen (ClutterActor *actor) return TRUE; } -/** +/* * * This gets the top level origin, it is, the position of the stage in * the global screen. You can see it as the absolute display position @@ -898,7 +907,7 @@ _is_actor_on_screen (ClutterActor *actor) * FIXME: only the case with x11 is implemented, other backends are * required * - **/ + */ static void _get_top_level_origin (ClutterActor *actor, gint *x, @@ -1116,14 +1125,14 @@ cally_actor_action_get_keybinding (AtkAction *action, /* Misc functions */ -/** +/* * Checks if the parent actor, and his parent, etc is all visible * Used to check the showing property * * FIXME: the same functionality is implemented on clutter since version 0.8.4 * by clutter_actor_get_paint_visibility, so we should change this function * if a clutter version update is made - **/ + */ static gboolean _cally_actor_all_parents_visible (ClutterActor *actor) { @@ -1352,23 +1361,24 @@ _cally_actor_release_action (CallyActor *cally_actor) /** * cally_actor_add_action: + * @cally_actor: a #CallyActor * @action_name: the action name * @action_description: the action description * @action_keybinding: the action keybinding * @action_func: the callback of the action, to be executed with do_action * - * Adds a new action to be accessed with the AtkAction interface. + * Adds a new action to be accessed with the #AtkAction interface. * * Return value: added action id, or 0 if failure * - * Since: 1.2 + * Since: 1.4 */ guint -cally_actor_add_action (CallyActor *cally_actor, - const gchar *action_name, - const gchar *action_description, - const gchar *action_keybinding, - CallyActionFunc action_func) +cally_actor_add_action (CallyActor *cally_actor, + const gchar *action_name, + const gchar *action_description, + const gchar *action_keybinding, + CallyActionFunc action_func) { CallyActorActionInfo *info = NULL; CallyActorPrivate *priv = NULL; @@ -1404,17 +1414,18 @@ cally_actor_add_action (CallyActor *cally_actor, /** * cally_actor_remove_action: + * @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 cally_actor_add_action() * - * Return value: TRUE if the operation was succesful, FALSE otherwise + * Return value: %TRUE if the operation was succesful, %FALSE otherwise * - * Since: 1.2 + * Since: 1.4 */ gboolean cally_actor_remove_action (CallyActor *cally_actor, - gint action_id) + gint action_id) { GList *list_node = NULL; CallyActorPrivate *priv = NULL; @@ -1435,18 +1446,19 @@ cally_actor_remove_action (CallyActor *cally_actor, } /** - * cally_actor_remove_action: - * @action_name: the name of the action + * cally_actor_remove_action_by_name: + * @cally_actor: a #CallyActor + * @action_name: the name of the action to remove * - * Removes a action, using the @action_name used when the action was added - * with cally_actor_add_action + * Removes an action, using the @action_name used when the action was added + * with cally_actor_add_action() * - * Return value: TRUE if the operation was succesful, FALSE otherwise + * Return value: %TRUE if the operation was succesful, %FALSE otherwise * - * Since: 1.2 + * Since: 1.4 */ gboolean -cally_actor_remove_action_by_name (CallyActor *cally_actor, +cally_actor_remove_action_by_name (CallyActor *cally_actor, const gchar *action_name) { GList *node = NULL; diff --git a/clutter/cally/cally-clone.c b/clutter/cally/cally-clone.c index 0bde12053..9ddf6f958 100644 --- a/clutter/cally/cally-clone.c +++ b/clutter/cally/cally-clone.c @@ -21,16 +21,53 @@ */ /** - * SECTION:callyclutterclone + * SECTION:cally-clone + * @Title: CallyClone * @short_description: Implementation of the ATK interfaces for a #ClutterClone * @see_also: #ClutterClone * - * #CallyClutterClone implements the required ATK interfaces of #ClutterClone + * #CallyClone implements the required ATK interfaces of #ClutterClone * * In particular it sets a proper role for the clone, as just a image, * as it is the sanest and simplest approach. + */ + +/* Design rationale for CallyClone: * - * Check http://lists.o-hand.com/clutter/3797.html for more information + * In the old times, it was just ClutterCloneTexture. So, from a a11y POV + * CallyCloneTexture was just another image, like ClutterTexture, and if + * it was a clone was irrevelant. So on cally-0.8, CallyCloneTexture + * expose a object with role ATK_ROLE_IMAGE. But now, ClutterClone is more + * general. You can clone any object, including groups, and made things + * like have one text entry, and a clone with different properties in the + * same window, updated both at once. + * + * The question is if the idea is have a ClutterClone as a "first-class" + * citizen inside the stage hierarchy (full clone), or it is just supposed + * to be a mirror image of the original object. + * + * In the case of the a11y POV this would mean that if the text changes on + * the source, the clone should emit as well the text-changing signals. + * + * As ClutterClone smartly just paint the same object with different + * parameters, this would mean that it should be the cally object the one + * that should replicate the source clutter hierarchy to do that, + * something that just sound crazy. + * + * Taking into account that: + * + * - ClutterClone doesn't re-emit mirrored signals from the source + * I think that likely the answer would be "yes, it is just a + * mirrored image, not a real full clone". + * + * - You can't interact directly with the clone (ie: focus, and so on). + * Its basic usage (right now) is clone textures. + * + * Any other solution could be overwhelming. + * + * I think that the final solution would be that ClutterClone from the + * a11y POV should still be managed as a image (with the proper properties, + * position, size, etc.). */ #include "cally-clone.h" diff --git a/clutter/cally/cally-group.c b/clutter/cally/cally-group.c index ddcd9f81d..d83c552e9 100644 --- a/clutter/cally/cally-group.c +++ b/clutter/cally/cally-group.c @@ -24,14 +24,17 @@ */ /** - * SECTION:callycluttergroup + * SECTION:cally-group + * @Title: CallyGroup * @short_description: Implementation of the ATK interfaces for a #ClutterGroup * @see_also: #ClutterGroup * * #CallyClutterGroup implements the required ATK interfaces of #ClutterGroup * In particular it exposes: + * * - * Each of the Clutter actors contained in the Clutter Group. + * Each of the Clutter actors contained in the + * Group. * */ @@ -65,7 +68,17 @@ cally_group_init (CallyGroup *group) /* nothing to do yet */ } -AtkObject* +/** + * cally_group_new: + * @actor: a #ClutterGroup + * + * Creates a #CallyGroup for @actor + * + * Return value: the newly created #CallyGroup + * + * Since: 1.4 + */ +AtkObject * cally_group_new (ClutterActor *actor) { GObject *object = NULL; diff --git a/clutter/cally/cally-rectangle.c b/clutter/cally/cally-rectangle.c index 934beb996..aff7f31f3 100644 --- a/clutter/cally/cally-rectangle.c +++ b/clutter/cally/cally-rectangle.c @@ -21,11 +21,11 @@ */ /** - * SECTION:callyclutterrectangle + * SECTION:cally-rectangle * @short_description: Implementation of the ATK interfaces for a #ClutterRectangle * @see_also: #ClutterRectangle * - * #CallyClutterRectangle implements the required ATK interfaces of #ClutterRectangle + * #CallyRectangle implements the required ATK interfaces of #ClutterRectangle * * In particular it sets a proper role for the rectangle. */ diff --git a/clutter/cally/cally-root.c b/clutter/cally/cally-root.c index b7897534a..f919c8531 100644 --- a/clutter/cally/cally-root.c +++ b/clutter/cally/cally-root.c @@ -21,19 +21,18 @@ */ /** - * SECTION:callyroot + * SECTION:cally-root * @short_description: Root object for the CALLY toolkit * @see_also: #ClutterStage * * #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 + * 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). - * + * the #GObject used in the atk_object_initialize() is the + * #ClutterStageManager). */ #include diff --git a/clutter/cally/cally-stage.c b/clutter/cally/cally-stage.c index 57f037be4..720b881a7 100644 --- a/clutter/cally/cally-stage.c +++ b/clutter/cally/cally-stage.c @@ -21,11 +21,12 @@ */ /** - * SECTION:callystage + * SECTION:cally-stage + * @Title: CallyStage * @short_description: Implementation of the ATK interfaces for a #ClutterStage * @see_also: #ClutterStage * - * #CallyStage implements the required ATK interfaces of #ClutterStage + * #CallyStage implements the required ATK interfaces for #ClutterStage * */ diff --git a/clutter/cally/cally-text.c b/clutter/cally/cally-text.c index 3ca103c31..008613a7e 100644 --- a/clutter/cally/cally-text.c +++ b/clutter/cally/cally-text.c @@ -29,13 +29,13 @@ * @short_description: Implementation of the ATK interfaces for a #ClutterText * @see_also: #ClutterText * - * #CallyClutterText implements the required ATK interfaces of + * #CallyText implements the required ATK interfaces of * #ClutterText, #AtkText and #AtkEditableText * * */ -/** +/* * IMPLEMENTATION NOTES: * * * AtkText: There are still some methods not implemented yet: diff --git a/clutter/cally/cally-texture.c b/clutter/cally/cally-texture.c index 13c3a6095..df0a67abf 100644 --- a/clutter/cally/cally-texture.c +++ b/clutter/cally/cally-texture.c @@ -21,11 +21,12 @@ */ /** - * SECTION:callycluttertexture + * SECTION:cally-texture + * @Title: CallyTexture * @short_description: Implementation of the ATK interfaces for a #ClutterTexture * @see_also: #ClutterTexture * - * #CallyClutterTexture implements the required ATK interfaces of #ClutterTexture + * #CallyTexture implements the required ATK interfaces of #ClutterTexture * * In particular it sets a proper role for the texture. */