docs: Fix Cally documentation

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,
+cally_actor_add_action (CallyActor      *cally_actor,
-                        const gchar *action_name,
+                        const gchar     *action_name,
-                        const gchar *action_description,
+                        const gchar     *action_description,
-                        const gchar *action_keybinding,
+                        const gchar     *action_keybinding,
-                        CallyActionFunc action_func)
+                        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:
+ * cally_actor_remove_action_by_name:
- * @action_name: the name of the action
+ * @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
+ * Removes an action, using the @action_name used when the action was added
- * with cally_actor_add_action
+ * 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;

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"

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:
+ *
  * <itemizedlist>
- * <listitem>Each of the Clutter actors contained in the Clutter Group.</listitem>
+ *   <listitem><simpara>Each of the Clutter actors contained in the
+ *   Group.</simpara></listitem>
  * </itemizedlist>
  */
 
@@ -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;

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

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
+ * Somewhat equivalent to #GailTopLevel. We consider that this class
- * expose the a11y information of the ClutterStageManager, as the
+ * 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
+ * the #GObject used in the atk_object_initialize() is the
- * ClutterStageManager).
+ * #ClutterStageManager).
- *
  */
 
 #include <clutter/clutter.h>

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

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:

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