some more docs...

SVN revision: 9038

legacy/evas/evas.c.in

@@ -244,12 +244,13 @@ make install
 
 
 @todo (1.0) Document API
+@todo (1.0) Evas engine that renders to Evas_Objects
 @todo (1.0) OpenGL engine needs to use texture meshes
 @todo (1.0) OpenGL engine needs texture cache and size setting
 @todo (1.0) OpenGL Engine needs YUV import API to YUV texture
 @todo (1.0) All engines need pixel import API
 @todo (1.0) Add parital render through composite layer api to engines
-@todo (1.0) Move callback processing to a queue and do it asynchronously
+@todo (1.0) Move callback processing to a queue and do it asynchronously???
 @todo (1.0) Add button grabbing
 @todo (1.0) Add generic object method call system
 @todo (1.0) Add callbacks set for smart object parents to be set on all child smart objects too.
@@ -259,7 +260,7 @@ make install
 @todo (1.0) Add font listing calls
 @todo (1.0) Add ability to check image comments & disk format
 @todo (1.0) Add group objects
-@todo (1.0) Export engine rnedering etc. API cleanly to Evas API
+@todo (1.0) Export engine rendering API cleanly to Evas API
 @todo (1.0) Add smart object ability to provide rendering callback
 @todo (1.1) Make freetype optional and put in optional graymap font engine
 @todo (1.1) Free images if object invisible (and put back in chache)

legacy/evas/src/lib/canvas/evas_data.c

@@ -3,10 +3,35 @@
 #include "Evas.h"
 
 /**
- * To be documented.
- *
- * FIXME: To be fixed.
+ * Set an attached data pointer to an object with a given string key.
+ * @param obj The object to attach the data pointer to
+ * @param key The string key for the data to access it
+ * @param data The ponter to the data to be attached
  * 
+ * This attaches the pointer @p data to the object @p obj given the string
+ * @p key. This pointer will stay "hooked" to the object until a new pointer
+ * with the same string key is attached with evas_object_data_set() or it is
+ * deleted with evas_object_data_del(). On deletion of the object @p obj, the
+ * pointers will not be accessible from the object anymore.
+ * 
+ * You can find the pointer attached under a string key using 
+ * evas_object_data_get(). It is the job of the calling application to free
+ * any data pointed to by @p data when it is no longer required.
+ * 
+ * If @p data is NULL, the old value stored at @p key will be removed but no
+ * new value will be stored. This is synonymous with calling 
+ * evas_object_data_del() with @p obj and @p key.
+ * 
+ * Example:
+ * 
+ * @code
+ * int *my_data;
+ * extern Evas_Object *obj;
+ * 
+ * my_data = malloc(500);
+ * evas_object_data_set(obj, "name_of_data", my_data);
+ * printf("The data that was attached was %p\n", evas_object_data_get(obj, "name_of_data"));
+ * @endcode
  */
 void
 evas_object_data_set(Evas_Object *obj, const char *key, const void *data)
@@ -19,7 +44,7 @@ evas_object_data_set(Evas_Object *obj, const char *key, const void *data)
    if (!key) return;
    
    evas_object_data_del(obj, key);
-   
+   if (data == NULL) return;
    node = malloc(sizeof(Evas_Data_Node));
    node->key = strdup(key);
    node->data = (void *)data;
@@ -27,10 +52,29 @@ evas_object_data_set(Evas_Object *obj, const char *key, const void *data)
 }
 
 /**
- * To be documented.
- *
- * FIXME: To be fixed.
+ * Return an attached data pointer by its given string key.
+ * @param obj The object to which the data was attached
+ * @param key The string key the data was stored under
+ * @return The data pointer stored, or NULL if none was stored
  * 
+ * This function will return the data pointer attached to the object @p obj
+ * stored using the string key @p key. If the object is valid and data was
+ * stored under the given key, the pointer that was stored will be reuturned.
+ * If this is not the case, NULL will be returned, signifying an invalid object
+ * or non-existent key. It is possible a NULL pointer was stored given that
+ * key, but this situation is non-sensical and thus can be considered an error
+ * as well. NULL pointers are never stored as this is the return value if an
+ * error occurs.
+ * 
+ * Example:
+ * 
+ * @code
+ * int *my_data;
+ * extern Evas_Object *obj;
+ * 
+ * my_data = evas_object_data_get(obj, "name_of_my_data");
+ * if (my_data) printf("Data stored was %p\n", my_data);
+ * else printf("No data was stored on the object\n");
  */
 void *
 evas_object_data_get(Evas_Object *obj, const char *key)
@@ -58,10 +102,23 @@ evas_object_data_get(Evas_Object *obj, const char *key)
 }
 
 /**
- * To be documented.
- *
- * FIXME: To be fixed.
+ * Delete at attached data pointer from an object.
+ * @param obj The object to delete the data pointer from
+ * @param key The string key the data was stored under
+ * @return The original data pointer stored at @p key on @p obj
  * 
+ * This will remove thee stored data pointer from @p obj stored under @p key,
+ * and return the original pointer stored under @p key, if any, nor NULL if
+ * nothing was stored under that key.
+ * 
+ * Example:
+ * 
+ * @code
+ * int *my_data;
+ * extern Evas_Object *obj;
+ * 
+ * my_data = evas_object_data_del(obj, "name_of_my_data");
+ * @endcode
  */
 void *
 evas_object_data_del(Evas_Object *obj, const char *key)