Improve documentation for Evas, Ecore, Edje and Elementary.

Work by:
 - Thiago R. Masaki (mostly)
 - Fabiano Fidencio
 - Gustavo Lima


SVN revision: 42552

legacy/edje/src/lib/edje_cache.c

@@ -1,6 +1,25 @@
 /*
  * vim:ts=8:sw=3:sts=8:noexpandtab:cino=>5n-3f0^-2{2
  */
+/* EDJE - EFL graphical design and layout library based on Evas
+ * Copyright (C) 2008 Cedric Bail
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library;
+ * if not, see <http://www.gnu.org/licenses/>.
+ */
+
+
 
 #ifdef HAVE_CONFIG_H
 # include <config.h>
@@ -438,8 +457,43 @@ _edje_file_cache_shutdown(void)
 
 
 
+/**
+ * @endcond
+ */
 
+/*============================================================================*
+ *                                 Global                                     *
+ *============================================================================*/
 
+/*============================================================================*
+ *                                   API                                      *
+ *============================================================================*/
+
+/**
+ * @addtogroup Edje_cache_Group Cache
+ *
+ * @brief These functions provide an abstraction layer between the
+ * application code and the interface, while allowing extremely
+ * flexible dynamic layouts and animations.
+ *
+ * For more information, you can look at the @ref tutorial_list_page.
+ *
+ * @{
+ */
+
+/**
+ * @brief Set the file cache size.
+ *
+ * @param count The file cache size in edje file units. Default is 16.
+ *
+ * This function sets the file cache size. Edje keeps this cache in
+ * order to prevent duplicates of edje file entries in memory. The
+ * file cache size can be retrieved with edje_file_cache_get().
+ *
+ * @see edje_file_cache_get()
+ * @see edje_file_cache_flush()
+ *
+ */
 
 EAPI void
 edje_file_cache_set(int count)
@@ -449,12 +503,38 @@ edje_file_cache_set(int count)
    _edje_cache_file_clean();
 }
 
+/**
+ * @brief Return the file cache size.
+ *
+ * @return The file cache size in edje file units. Default is 16.
+ *
+ * This function returns the file cache size set by
+ * edje_file_cache_set().
+ *
+ * @see edje_file_cache_set()
+ * @see edje_file_cache_flush()
+ *
+ */
+
 EAPI int
 edje_file_cache_get(void)
 {
    return _edje_file_cache_size;
 }
 
+/**
+ * @brief Clean the file cache.
+ *
+ * @return The file cache size.
+ *
+ * This function cleans the file cache entries, but keeps this cache's
+ * size to the last value set.
+ *
+ * @see edje_file_cache_set()
+ * @see edje_file_cache_get()
+ *
+ */
+
 EAPI void
 edje_file_cache_flush(void)
 {
@@ -466,6 +546,21 @@ edje_file_cache_flush(void)
    _edje_file_cache_size = ps;
 }
 
+/**
+ * @brief Set the collection cache size.
+ *
+ * @param count The collection cache size, in edje object units. Default is 16.
+ *
+ * This function sets the collection cache size. Edje keeps this cache
+ * in order to prevent duplicates of edje {collection,group,part}
+ * entries in memory. The collection cache size can be retrieved with
+ * edje_collection_cache_get().
+ *
+ * @see edje_collection_cache_get()
+ * @see edje_collection_cache_flush()
+ *
+ */
+
 EAPI void
 edje_collection_cache_set(int count)
 {
@@ -479,12 +574,38 @@ edje_collection_cache_set(int count)
    /* FIXME: freach in file hash too! */
 }
 
+/**
+ * @brief Return the collection cache size.
+ *
+ * @return The collection cache size, in edje object units. Default is 16.
+ *
+ * This function returns the collection cache size set by
+ * edje_collection_cache_set().
+ *
+ * @see edje_collection_cache_set()
+ * @see edje_collection_cache_flush()
+ *
+ */
+
 EAPI int
 edje_collection_cache_get(void)
 {
    return _edje_collection_cache_size;
 }
 
+/**
+ * @brief Clean the collection cache.
+ *
+ * @return The collection cache size.
+ *
+ * This function cleans the collection cache, but keeps this cache's
+ * size to the last value set.
+ *
+ * @see edje_collection_cache_set()
+ * @see edje_collection_cache_get()
+ *
+ */
+
 EAPI void
 edje_collection_cache_flush(void)
 {

legacy/edje/src/lib/edje_container.c

@@ -168,6 +168,46 @@ _edje_item_recalc(Edje_Item *ei)
 
 
 /*****************************/
+/**
+ * @endcond
+ */
+
+/*============================================================================*
+ *                                 Global                                     *
+ *============================================================================*/
+
+/*============================================================================*
+ *                                   API                                      *
+ *============================================================================*/
+
+/**
+ * @addtogroup Edje_container_Group Container
+ *
+ * @brief These functions provides an abstraction layer between the application
+ * code and the interface, while allowing extremely flexible dynamic layouts
+ * and animations.
+ *
+ * For more information, you can look at the @ref tutorial_list_page.
+ *
+ * @{
+ */
+
+/**
+ * @brief Create an edje item.
+ *
+ * @param cl The edje item of type Edje_Item_Class.
+ * @param data The edje item data.
+ *
+ * @return The new edje item created.
+ *
+ * This function creates an new edje item. The edje item data can be
+ * retrieved with edje_item_data_get().
+ *
+ * @see edje_item_del()
+ * @see edje_item_data_set()
+ * @see edje_item_data_get()
+ *
+ */
 
 Edje_Item *
 edje_item_add(Edje_Item_Class *cl, void *data)
@@ -182,6 +222,19 @@ edje_item_add(Edje_Item_Class *cl, void *data)
    return ei;
 }
 
+/**
+ * @brief Delete an edje item.
+ *
+ * @param ei The edje item to be deleted.
+ *
+ * This function deletes the edje item from memory.
+ *
+ * @see edje_item_add()
+ * @see edje_item_data_set()
+ * @see edje_item_data_get()
+ *
+ */
+
 void
 edje_item_del(Edje_Item *ei)
 {
@@ -197,6 +250,16 @@ edje_item_del(Edje_Item *ei)
    _edje_container_recalc(sd);
 }
 
+/**
+ * @brief Return the smart object of the edje item.
+ *
+ * @param ei The edje item wich the smart object of type Evas_Object is get
+ * from.
+ *
+ * This function returns the smart object in the edje item.
+ *
+ */
+
 Evas_Object *
 edje_item_container_get(Edje_Item *ei)
 {
@@ -205,6 +268,20 @@ edje_item_container_get(Edje_Item *ei)
 }
 
 /* an arbitary data pointer to use to track other data */
+/**
+ * @brief Set the edje item data.
+ *
+ * @param ei The edje item of type Edje_Item_Class.
+ * @param data The edje item data.
+ *
+ * This function set the data of the edje item. The edje item data can be
+ * retrieved with edje_item_data_get().
+ *
+ * @see edje_item_add()
+ * @see edje_item_del()
+ * @see edje_item_data_get()
+ *
+ */
 
 void
 edje_item_data_set(Edje_Item *ei, void *data)
@@ -212,6 +289,19 @@ edje_item_data_set(Edje_Item *ei, void *data)
    ei->data = data;
 }
 
+/**
+ * @brief Get the data of the edje item.
+ *
+ * @param ei The edje item of type Edje_Item_Class.
+ *
+ * This function get the data of the edje item set by edje_item_data_set().
+ *
+ * @see edje_item_data_set()
+ * @see edje_item_add()
+ * @see edje_item_del()
+ *
+ */
+
 void *
 edje_item_data_get(Edje_Item *ei)
 {
@@ -219,6 +309,7 @@ edje_item_data_get(Edje_Item *ei)
 }
 
 /* this object covers the entire item */
+
 void
 edje_item_overlay_object_set(Edje_Item *ei, Evas_Object *obj)
 {
@@ -231,6 +322,8 @@ edje_item_overlay_object_set(Edje_Item *ei, Evas_Object *obj)
      evas_object_smart_member_add(((Smart_Data *)(ei->sd))->smart_obj, obj);
 }
 
+
+
 Evas_Object *
 edje_item_overlay_object_get(Edje_Item *ei)
 {

legacy/edje/src/lib/edje_edit.c

@@ -74,6 +74,7 @@ _alloc(size_t size)
 /* INTERNALS */
 /*************/
 
+
 static Edje_Part_Description *
 _edje_part_description_find_byname(Edje *ed, const char *part, const char *state) //state include the value in the string (ex. "default 0.00")
 {
@@ -625,6 +626,23 @@ edje_edit_compiler_get(Evas_Object *obj)
 /*  GROUPS API  */
 /****************/
 
+/**
+ * @brief Add an edje (empty) group to an edje object's group set.
+ *
+ * @param obj The pointer to edje object.
+ * @param name The name of the group.
+ *
+ * @return 1 If it could allocate memory to the part group added
+ * or zero if not.
+ *
+ * This function adds, at run time, one more group, which will reside
+ * in memory, to the group set found in the .edj file which @a obj was
+ * loaded with. This group can be manipulated by other API functions,
+ * like @c edje_edit_part_add(), for example. If desired, the new
+ * group can be actually commited the respective .edj by use of @c
+ * edje_edit_save().
+ *
+ */
 EAPI Eina_Bool
 edje_edit_group_add(Evas_Object *obj, const char *name)
 {
@@ -703,7 +721,18 @@ edje_edit_group_add(Evas_Object *obj, const char *name)
    return 1;
 }
 
-
+/**
+ * @brief Delete an edje object's current group.
+ *
+ * @param obj The pointer to the edje object.
+ *
+ * @return @c 1 on success, @c 0 on failure.
+ *
+ * This function deletes the group which @a obj is set to. This
+ * operation can be commited the the .edj file the object was loaded
+ * with by use of @c edje_edit_save().
+ *
+ */
 EAPI Eina_Bool
 edje_edit_group_del(Evas_Object *obj)
 {

legacy/edje/src/lib/edje_main.c

@@ -10,12 +10,42 @@ static int initted = 0;
 Eina_Mempool *_edje_real_part_mp = NULL;
 Eina_Mempool *_edje_real_part_state_mp = NULL;
 
-/************************** API Routines **************************/
 
-/** Initialize the EDJE library.
+/*============================================================================*
+ *                                   API                                      *
+ *============================================================================*/
+
+/**
+ * @addtogroup Edje_main_Group Main
  *
- * @return The new init count.
+ * @brief These functions provide an abstraction layer between the
+ * application code and the interface, while allowing extremely
+ * flexible dynamic layouts and animations.
+ *
+ * For more information, you can look at the @ref tutorial_list_page.
+ *
+ * @{
  */
+
+/**
+ * @brief Initialize the edje library.
+ *
+ * @return The new init count. The initial value is zero.
+ *
+ * This function initializes the ejde library, making the propers
+ * calls to initialization functions. It makes calls to functions
+ * eina_init(), ecore_job_init(), embryo_init() and eet_init() so
+ * there is no need to call those functions again in your code. To
+ * shutdown edje there is a function edje_shutdown().
+ *
+ * @see edje_shutdown()
+ * @see eina_init()
+ * @see ecore_job_init()
+ * @see embryo_init()
+ * @see eet_init()
+ *
+ */
+
 EAPI int
 edje_init(void)
 {
@@ -61,10 +91,24 @@ edje_init(void)
    return 0;
 }
 
-/** Shutdown the EDJE library.
+/**
+ * @brief Shutdown the edje library.
+ *
+ * @return Zero, always.
+ *
+ * This function shuts down the edje library. It calls the functions
+ * eina_shutdown(), ecore_job_shutdown(), embryo_shutdown() and
+ * eet_shutdown(), so there is no need to call these functions again
+ * in your code.
+ *
+ * @see edje_init()
+ * @see eina_shutdown()
+ * @see ecore_job_shutdown()
+ * @see embryo_shutdown()
+ * @see eet_shutdown()
  *
- * @return The new init count.
  */
+
 EAPI int
 edje_shutdown(void)
 {

legacy/edje/src/lib/edje_message_queue.c

@@ -12,6 +12,40 @@ static Ecore_Timer *job_loss_timer = NULL;
 static Eina_List *msgq = NULL;
 static Eina_List *tmp_msgq = NULL;
 
+/*============================================================================*
+ *                                   API                                      *
+ *============================================================================*/
+
+/**
+ * @addtogroup Edje_message_queue_Group Message_Queue
+ *
+ * @brief These functions provide an abstraction layer between the
+ * application code and the interface, while allowing extremely
+ * flexible dynamic layouts and animations.
+ *
+ * For more information, you can look at the @ref tutorial_list_page.
+ *
+ * @{
+ */
+
+/**
+ * @brief Send message to object.
+ *
+ * @param obj The edje object reference.
+ * @param type The type of message to send.
+ * @param id A identification number for the message.
+ * @param msg The message to be send.
+ *
+ *
+ * This function sends messages to this object and to all of its child
+ * objects, if applicable. The function that handles messages arriving
+ * at this edje object is is set with
+ * edje_object_message_handler_set().
+ *
+ * @see edje_object_message_handler_set()
+ *
+ */
+
 EAPI void
 edje_object_message_send(Evas_Object *obj, Edje_Message_Type type, int id, void *msg)
 {
@@ -30,6 +64,19 @@ edje_object_message_send(Evas_Object *obj, Edje_Message_Type type, int id, void
      }
 }
 
+/**
+ * @brief Set the message handler function for this an object.
+ *
+ * @param obj The edje object reference.
+ * @param func The function to handle messages.
+ * @param data The data to be associated to the message handler.
+ *
+ *
+ * This function associates a message handler function and data to the
+ * edje object.
+ *
+ */
+
 EAPI void
 edje_object_message_handler_set(Evas_Object *obj, void (*func) (void *data, Evas_Object *obj, Edje_Message_Type type, int id, void *msg), void *data)
 {
@@ -40,6 +87,17 @@ edje_object_message_handler_set(Evas_Object *obj, void (*func) (void *data, Evas
    _edje_message_cb_set(ed, func, data);
 }
 
+/**
+ * @brief Process an object's message queue.
+ *
+ * @param obj The edje object reference.
+ *
+ * This function goes through the object message queue processing the
+ * pending messages for *this* specific edje object. Normally they'd
+ * be processed only at idle time.
+ *
+ */
+
 EAPI void
 edje_object_message_signal_process(Evas_Object *obj)
 {
@@ -84,12 +142,21 @@ edje_object_message_signal_process(Evas_Object *obj)
      }
 }
 
+/**
+ * @brief Process all queued up edje messages.
+ *
+ * This function triggers the processing of messages addressed to any
+ * (alive) edje objects.
+ *
+ */
+
 EAPI void
 edje_message_signal_process(void)
 {
    _edje_message_queue_process();
 }
 
+
 static int
 _edje_dummy_timer(void *data __UNUSED__)
 {

legacy/edje/src/lib/edje_program.c

@@ -13,13 +13,35 @@ int             _edje_anim_count = 0;
 Ecore_Animator *_edje_timer = NULL;
 Eina_List      *_edje_animators = NULL;
 
-/************************** API Routines **************************/
 
-/* FIXDOC: Expand */
+/*============================================================================*
-/** Set the frametime
+ *                                   API                                      *
- * @param t The frametime
+ *============================================================================*/
+
+/**
+ * @addtogroup Edje_program_Group Program
+ *
+ * @brief These functions provide an abstraction layer between the
+ * application code and the interface, while allowing extremely
+ * flexible dynamic layouts and animations.
+ *
+ * For more information, you can look at the @ref tutorial_list_page.
+ *
+ * @{
+ */
+
+/**
+ * @brief Set edje trasitions' frame time.
+ *
+ * @param t The frame time, in seconds. Default value is 1/30.
+ *
+ * This function sets the edje built-in animations' frame time (thus,
+ * affecting their resolution) by calling
+ * ecore_animator_frametime_set(). This frame time can be retrieved
+ * with edje_frametime_get().
+ *
+ * @see edje_frametime_get()
  *
- * Sets the global frametime in seconds, by default this is 1/30.
  */
 EAPI void
 edje_frametime_set(double t)
@@ -27,11 +49,16 @@ edje_frametime_set(double t)
    ecore_animator_frametime_set(t);
 }
 
-/* FIXDOC: Expand */
+/**
-/** Get the frametime
+ * @brief Get edje trasitions' frame time.
- * @return The frametime
+ *
+ * @return The frame time, in seconds.
+ *
+ * This function returns the edje frame time set by
+ * edje_frametime_set().
+ *
+ * @see edje_frametime_set()
  *
- * Returns the frametime in seconds, by default this is 1/30.
  */
 EAPI double
 edje_frametime_get(void)
@@ -39,13 +66,15 @@ edje_frametime_get(void)
    return ecore_animator_frametime_get();
 }
 
-/* FIXDOC: Expand */
+/**
-/** Add a callback for a signal emitted by @a obj.
+ * @brief Add a callback for a signal emitted by @a obj.
- * @param obj A valid Evas_Object handle
+ *
- * @param emission The signal name
+ * @param obj A valid Evas_Object handle.
- * @param source The signal source
+ * @param emission The signal's name.
- * @param func The callback function to be executed when the signal is emitted
+ * @param source The signal's source.
- * @param data A pointer to data to pass in to the callback function
+ * @param func The callback function to be executed when the signal is
+ * emitted.
+ * @param data A pointer to data to pass in to the callback function.
  *
  * Connects a callback function to a signal emitted by @a obj.
  * In EDC, a program can emit a signal as follows:
@@ -69,21 +98,21 @@ edje_frametime_get(void)
  * edje_object_callback_add(obj, "a_signal", "a_source", cb_signal, data);
  * @endcode
  *
- * Here, @a data is an arbitrary pointer to be used as desired.
+ * Here, @a data is an arbitrary pointer to be used as desired.  Note
- * Note that @a emission and @a source correspond respectively to first and
+ * that @a emission and @a source correspond respectively to the first
- * second parameters to the SIGNAL_EMIT action.
+ * and the second parameters at the SIGNAL_EMIT action.
  *
- * Internal edje signals can also be attached to, and globs can be in either
+ * Internal edje signals can also be attached to, and globs can occur
- * the emission or source name. e.g.
+ * in either the emission or source name, e.g.
  *
  * @code
  * edje_object_callback_add(obj, "mouse,down,*", "button.*", NULL);
  * @endcode
  *
  * Here, any mouse down events on an edje part whose name begins with
- * "button." will trigger the callback. The actual signal and source name
+ * "button." will trigger the callback. The actual signal and source
- * will be passed in to the @a emission and @a source parameters of the
+ * names will be passed in to the @a emission and @a source parameters
- * callback function. (e.g. "mouse,down,2" and "button.close").
+ * of the callback function (e.g. "mouse,down,2" and "button.close").
  */
 EAPI void
 edje_object_signal_callback_add(Evas_Object *obj, const char *emission, const char *source, void (*func) (void *data, Evas_Object *o, const char *emission, const char *source), void *data)
@@ -112,17 +141,23 @@ edje_object_signal_callback_add(Evas_Object *obj, const char *emission, const ch
      _edje_callbacks_patterns_clean(ed);
 }
 
-/** Remove a callback from an object
+/**
- * @param obj A valid Evas_Object handle
+ * @brief Remove a signal-triggered callback from an object.
- * @param emission the emission string
+ *
- * @param source the source string
+ * @param obj A valid Evas_Object handle.
- * @param func the callback function
+ * @param emission The emission string.
- * @return the data pointer
+ * @param source The source string.
+ * @param func The callback function.
+ * @return The data pointer
+ *
+ * This function removes a callback, previously attached to the
+ * emittion of a signal, from the object @a obj. The parameters @a
+ * emission, @a source and @a func must match exactly those passed to
+ * a previous call to edje_object_signal_callback_add(). The data
+ * pointer that was passed to this call will be returned.
+ *
+ * @see edje_object_signal_callback_add().
  *
- * Removes a callback from an object. The parameters @a emission, @a source
- * and @a func must match exactly those passed to a previous call to
- * edje_object_signal_callback_add(). The data pointer that was passed to
- * this call will be returned.
  */
 EAPI void *
 edje_object_signal_callback_del(Evas_Object *obj, const char *emission, const char *source, void (*func) (void *data, Evas_Object *o, const char *emission, const char *source))
@@ -166,24 +201,22 @@ edje_object_signal_callback_del(Evas_Object *obj, const char *emission, const ch
    return NULL;
 }
 
-/* FIXDOC: Verify/Expand */
+/**
-/** Send a signal to the Edje object
+ * @brief Send a signal to an edje object.
- * @param obj A vaild Evas_Object handle
- * @param emission The signal
- * @param source The signal source
  *
- * This sends a signal to the edje object.
+ * @param obj A valid Evas_Object handle.
+ * @param emission The signal's name.
+ * @param source The signal's source.
  *
- * An edje program can respond to a signal by specifying matching 'signal'
+ * This function sends a signal to the object @a obj. An edje program
- * and 'source' fields.
+ * can respond to a signal by specifying matching 'signal' and
- *
+ * 'source' fields.
- * E.g.
  *
  * @code
  * edje_object_signal_emit(obj, "a_signal", "");
  * @endcode
  *
- * will trigger a program whose edc is:
+ * will trigger a program whose EDC block is:
  *
  * @code
  * program {
@@ -194,7 +227,7 @@ edje_object_signal_callback_del(Evas_Object *obj, const char *emission, const ch
  * }
  * @endcode
  *
- * FIXME should this signal be sent to children also?
+ * FIXME: should this signal be sent to children also?
  */
 EAPI void
 edje_object_signal_emit(Evas_Object *obj, const char *emission, const char *source)
@@ -209,12 +242,18 @@ edje_object_signal_emit(Evas_Object *obj, const char *emission, const char *sour
 }
 
 /* FIXDOC: Verify/Expand */
-/** Set the Edje to play or pause
+/**
- * @param obj A valid Evas_Object handle
+ * @brief Set the edje object to playing or paused states.
- * @param play Play instruction (1 to play, 0 to pause)
+ *
+ * @param obj A valid Evas_Object handle.
+ * @param play Object state (1 to playing, 0 to pauseed).
+ *
+ * This function sets the edje object @a obj to playing or paused
+ * states, depending on the parameter @a play.  This has no effect if
+ * the object was already at that state.
+ *
+ * @see edje_object_play_get().
  *
- * This sets the Edje to play or pause depending on the parameter.
- * This has no effect if the Edje is already in that state.
  */
 EAPI void
 edje_object_play_set(Evas_Object *obj, int play)
@@ -252,11 +291,19 @@ edje_object_play_set(Evas_Object *obj, int play)
      }
 }
 
-/* FIXDOC: Verify/Expand */
+/**
-/** Get the Edje play/pause state
+ * @brief Get the edje object's play/pause state.
- * @param obj A valid Evas_Object handle
+ *
- * @return 0 if Edje not connected, Edje delete_me, or Edje paused\n
+ * @param obj A valid Evas_Object handle.
- * 1 if Edje set to play
+ * @return @c 0 if the object is not connected, its @c delete_me flag
+ * is set, or it is at paused state; @c 1 if the object is at playing
+ * state.
+ *
+ * This function tells if an edje object is playing or not. This state
+ * is set by edje_object_play_set().
+ *
+ * @see edje_object_play_set().
+ *
  */
 EAPI int
 edje_object_play_get(const Evas_Object *obj)
@@ -271,11 +318,18 @@ edje_object_play_get(const Evas_Object *obj)
 }
 
 /* FIXDOC: Verify/Expand */
-/** Set Animation state
+/**
- * @param obj A valid Evas_Object handle
+ * @brief Set the object's animation state.
- * @param on Animation State
+ *
+ * @param obj A valid Evas_Object handle.
+ * @param on Animation State.
+ *
+ * This function starts or stops an edje object's animation. The
+ * information if it's runnig can be retrieved by
+ * edje_object_animation_get().
+ *
+ * @see edje_object_animation_get()
  *
- * Stop or start an Edje animation.
  */
 EAPI void
 edje_object_animation_set(Evas_Object *obj, int on)
@@ -334,12 +388,19 @@ edje_object_animation_set(Evas_Object *obj, int on)
    _edje_unblock(ed);
 }
 
-/* FIXDOC: Verify/Expand */
+/**
-/** Get the animation state
+ * @brief Get the edje object's animation state.
- * @param obj A valid Evas_Object handle
+ *
- * @return 0 on Error or if not animated\n
+ * @param obj A valid Evas_Object handle.
- * 1 if animated
+ * @return @c 0 on error or if object is not animated; @c 1 if animated.
+ *
+ * This function returns if the animation is playing or not. The
+ * animation state is set by edje_object_play_set().
+ *
+ * @see edje_object_animation_set().
+ *
  */
+
 EAPI int
 edje_object_animation_get(const Evas_Object *obj)
 {