documentation

9 files changed, 315 insertions, 33 deletions

diff --git a/src/include/eiotas_board.h b/src/include/eiotas_board.h
index 4813808..6572faf 100644
--- a/src/include/eiotas_board.h
+++ b/src/include/eiotas_board.h
@@ -25,16 +25,42 @@
 
 #include <eina_hash.h>
 
+/**
+ * @typedef Eiotas_Board
+ * Type for a Particle Merging Door.
+ */
 typedef struct _Eiotas_Board Eiotas_Board;
 
+/**
+ * @struct _Eiotas_Board
+ * Struct for a Particle Merging Door.
+ */
 struct _Eiotas_Board {
-    Eiotas_Iota         iota;           /* structural info */
-    Eiotas_User_Bits    user_bits;      /* user bits */
-    Eina_Hash           *postponed;     /* TODO Particles */
+    Eiotas_Iota         iota;           /**< structural info */
+    Eiotas_User_Bits    user_bits;      /**< user bits */
+    Eina_Hash           *postponed;     /**< TODO Particles */
 };
 
+/**
+ * @brief Free allocated resources.
+ *
+ * @param board The Eiotas_Board to free.
+ *
+ * This function will free all it's user data using user_bits ... FIXME
+ */
 void eiotas_board_free(Eiotas_Board *board);
 
+/**
+ * @brief Allocate the resources.
+ *
+ * @param name The name of this door.
+ * @param parent The direct hierarchical parent Eiotas_Room.
+ * @param user_bits A Eiotas_User_Bits initilized with user side pointers.
+ *
+ * @return the new allocated Eiotas_Board @c NULL on failure
+ *
+ * @see Eiotas_User_Bits
+ */
 EAPI Eiotas_Board*  eiotas_board_add(const char* name, Eiotas_Room *parent, Eiotas_User_Bits *user_bits);
 
 #endif // __EIOTAS_BOARD_H__
diff --git a/src/include/eiotas_door.h b/src/include/eiotas_door.h
index 05060c4..318779f 100644
--- a/src/include/eiotas_door.h
+++ b/src/include/eiotas_door.h
@@ -25,15 +25,41 @@
 
 #include <eina_types.h>
 
+/**
+ * @typedef Eiotas_Door
+ * Type for a basic Door.
+ */
 typedef struct _Eiotas_Door Eiotas_Door;
 
+/**
+ * @struct _Eiotas_Door
+ * Struct for a basic Door.
+ */
 struct _Eiotas_Door {
-    Eiotas_Iota         iota;       /* structural info */
-    Eiotas_User_Bits    user_bits;  /* user bits */
+    Eiotas_Iota         iota;       /**< structural info */
+    Eiotas_User_Bits    user_bits;  /**< user bits */
 };
 
+/**
+ * @brief Free allocated resources.
+ *
+ * @param door The Eiotas_Door to free.
+ *
+ * This function will free all it's user data using user_bits ... FIXME
+ */
 void eiotas_door_free(Eiotas_Door *door);
 
+/**
+ * @brief Allocate the resources.
+ *
+ * @param name The name of this door.
+ * @param parent The direct hierarchical parent Eiotas_Room.
+ * @param user_bits A Eiotas_User_Bits initilized with user side pointers.
+ *
+ * @return the new allocated Eiotas_Door @c NULL on failure
+ *
+ * @see Eiotas_User_Bits
+ */
 EAPI Eiotas_Door*   eiotas_door_add(const char* name, Eiotas_Room *parent, Eiotas_User_Bits *user_bits);
 
 #endif // __EIOTAS_DOOR_H__
diff --git a/src/include/eiotas_iota.h b/src/include/eiotas_iota.h
index 12f093b..d54ae61 100644
--- a/src/include/eiotas_iota.h
+++ b/src/include/eiotas_iota.h
@@ -21,6 +21,10 @@
 
 #include <eina_stringshare.h>
 
+/**
+ * @enum _Eiotas_Type
+ * List of available Eiotas_Iota
+ */
 typedef enum _Eiotas_Type
 {
    EIOTAS_TYPE_SPIN=0,
@@ -30,18 +34,37 @@ typedef enum _Eiotas_Type
    EIOTAS_TYPE_COUNT
 } Eiotas_Type;
 
+/**
+ * @typedef Eiotas_Iota
+ * Type for structural and  hierachical info
+ */
 typedef struct _Eiotas_Iota Eiotas_Iota;
 
+/**
+ * @struct _Eiotas_Iota
+ * Struct for structural and  hierachical info.
+ */
 struct _Eiotas_Iota {
-    Eiotas_Type         type;       /* type of the iota */
-    Eiotas_Iota         *spin;      /* top level iota which is a Eiotas_Spin */
-    Eiotas_Iota         *parent;    /* direct parent in the hierarchy */
-    Eina_Stringshare    *name;      /* iota's name */
-    Eina_Stringshare    *path;      /* full path to this iota */
+    Eiotas_Type         type;       /**< type of the iota */
+    Eiotas_Iota         *spin;      /**< top level iota which is a Eiotas_Spin */
+    Eiotas_Iota         *parent;    /**< direct parent in the hierarchy */
+    Eina_Stringshare    *name;      /**< iota's name */
+    Eina_Stringshare    *path;      /**< full path to this Eiotas_Iota */
 };
 
+/**
+ * @brief Print iota information using EINA_LOG_DBG.
+ *
+ * @param iota The Eiotas_Iota to show.
+ */
 EAPI void eiotas_iota_show(Eiotas_Iota *iota);
 
+/**
+ * @brief Free allocated resources.
+ *
+ * @param iota The Eiotas_Iota to free.
+ *
+ */
 void eiotas_iota_free(Eiotas_Iota *iota);
 
 #define eiotas_iota_require_particle(_iota) eiotas_spin_require_particle((Eiotas_Spin*)(_iota)->spin)
diff --git a/src/include/eiotas_link.h b/src/include/eiotas_link.h
index 4692641..4cc4e44 100644
--- a/src/include/eiotas_link.h
+++ b/src/include/eiotas_link.h
@@ -19,11 +19,24 @@
 #ifndef __EIOTAS_LINK_H__
 #define __EIOTAS_LINK_H__
 
+/**
+ * @typedef Eiotas_Link
+ * Type for a Link between Eiotas_Iotas.
+ */
 typedef struct _Eiotas_Link Eiotas_Link;
 
+/**
+ * @struct _Eiotas_Link
+ * Struct for a Link between Eiotas_Iotas.
+ */
 struct _Eiotas_Link {
 };
 
+/**
+ * @brief Free allocated resources.
+ *
+ * @param link The Eiotas_Link to free.
+ */
 void eiotas_link_free(Eiotas_Link *link);
 
 #endif // __EIOTAS_LINK_H__
diff --git a/src/include/eiotas_main.h b/src/include/eiotas_main.h
index d7ef48c..d75ab96 100644
--- a/src/include/eiotas_main.h
+++ b/src/include/eiotas_main.h
@@ -21,6 +21,10 @@
 
 #include <eina_types.h>
 
+/**
+ * @typedef Eiotas_Version
+ * The version of Eiotas.
+ */
 typedef struct _Eiotas_Version
 {
    int major;    /**< Major component of the version */
@@ -32,8 +36,35 @@ EAPI extern Eiotas_Version *eiotas_version;
 
 EAPI extern int _eiotas_log_dom;
 
+/**
+ * @brief Initialize the Eiotas library.
+ *
+ * @return 1 or greater on success, 0 on error.
+ *
+ * This function sets up all the eiotas modules. It returns 0 on
+ * failure (that is, when one of the module fails to initialize),
+ * otherwise it returns the number of times it has already been
+ * called.
+ *
+ * When Eiotas is not used anymore, call eiotas_shutdown() to shut down
+ * the Eiotaslibrary.
+ */
 EAPI int eiotas_init();
 
+/**
+ * @brief Shut down the Eiotas library.
+ *
+ * @return 0 when all the modules are completely shut down, 1 or
+ * greater otherwise.
+ *
+ * This function shuts down the Eiotas library. It returns 0 when it has
+ * been called the same number of times than eiotas_init(). In that case
+ * it shut down all the Eiotas modules.
+ *
+ * Once this function succeeds (that is, @c 0 is returned), you must
+ * not call any of the Eiotas function anymore. You must call
+ * eiotas_init() again to use the Eiotas functions again.
+ */
 EAPI int eiotas_shutdown();
 
 #endif // __EIOTAS_MAIN_H__
diff --git a/src/include/eiotas_particle.h b/src/include/eiotas_particle.h
index 6897d89..3f74040 100644
--- a/src/include/eiotas_particle.h
+++ b/src/include/eiotas_particle.h
@@ -27,30 +27,75 @@
 
 #include "eiotas_iota.h"
 
+/**
+ * @typedef Eiotas_Particle
+ * Type for a Particle, holding data and spinning from Iotas to Iotas.
+ */
 typedef struct _Eiotas_Particle Eiotas_Particle;
 
+/**
+ * @struct _Eiotas_Particle
+ * Struct for a Particle, holding data and spinning from Iotas to Iotas.
+ */
 struct _Eiotas_Particle {
-    EINA_INLIST;
-    time_t ts;                          /* creation time */
-    Eiotas_Iota         *src;           /* where it's born */
-    Eiotas_Iota         *dst;           /* current destination */
-    Eina_Array          *dsts;          /* array of destinatinon strings */
-    Eina_Hash           *payload;       /* string data carried by this particle */
-    Eina_Inlist         *merged;        /* list of merged particles */
-    Eina_Array          *link_fields;   /* fields used to generate the link value */
-    Eina_Stringshare    *link_value;    /* computed from link_fields and paylod, used for pearing particles */
+    EINA_INLIST;                        /**< the Eina_Inlist info */
+    time_t ts;                          /**< creation time */
+    Eiotas_Iota         *src;           /**< where it's born */
+    Eiotas_Iota         *dst;           /**< current destination */
+    Eina_Array          *dsts;          /**< array of destinatinon strings */
+    Eina_Hash           *payload;       /**< string data carried by this particle */
+    Eina_Inlist         *merged;        /**< list of merged particles */
+    Eina_Array          *link_fields;   /**< fields used to generate the link value */
+    Eina_Stringshare    *link_value;    /**< computed from link_fields and paylod, used for pearing particles */
 };
 
+/**
+ * @brief Free allocated resources.
+ *
+ * @param particle The Eiotas_Particle to free.
+ *
+ * This function will free all the merged Eiotas_Particle
+ */
 void eiotas_particle_free(Eiotas_Particle *particle);
 
+/**
+ * @brief Allocate the resources.
+ *
+ * @return the new allocated Eiotas_Particle @c NULL on failure
+ */
 Eiotas_Particle* eiotas_particle_alloc();
 
+/**
+ * @brief Reset the Eiotas_Particle so that it can be required later.
+ *
+ * @param particle The Eiotas_Particle to reset
+ */
 EAPI void eiotas_particle_reset(Eiotas_Particle *particle);
 
+/**
+ * @brief Set @c src and @c ts timestamp.
+ *
+ * @param particle The Eiotas_Particle to init
+ * @param iota The Eiotas_Iota wich will be set as @c src
+ */
 EAPI void eiotas_particle_init(Eiotas_Particle *particle, Eiotas_Iota *iota);
 
+/**
+ * @brief Merge a particle into the other.
+ *
+ * @param particle The Eiotas_Particle to hold @p p
+ * @param p The Eiotas_Particle to be merged into @p particle
+ */
 EAPI void eiotas_particle_merge(Eiotas_Particle *particle, Eiotas_Particle *p);
 
+/**
+ * @brief Add destinations to the Eiotas_Particle
+ *
+ * @param particle The Eiotas_Particle to add destinations to
+ * @param destinations A comma separated list of destination "/room0/room1/.../doorx?action"
+ *
+ * This function will append each destination found to the destination list of the Eiotas_Particle.
+ */
 EAPI void eiotas_particle_add_destinations(Eiotas_Particle *particle, char* destinations);
 
 #endif // __EIOTAS_PARTICLE_H__
diff --git a/src/include/eiotas_room.h b/src/include/eiotas_room.h
index 877a91c..644dc0e 100644
--- a/src/include/eiotas_room.h
+++ b/src/include/eiotas_room.h
@@ -23,16 +23,41 @@
 
 #include <eina_hash.h>
 
+/**
+ * @typedef Eiotas_Room
+ * Type for a Room, which holds other child Eiotas_Iotas.
+ */
 typedef struct _Eiotas_Room Eiotas_Room;
 
+/**
+ * @struct _Eiotas_Room
+ * Struct for a Room, which holds other child Eiotas_Iotas.
+ */
 struct _Eiotas_Room {
-    Eiotas_Iota     iota;       /* structural info */
-    Eina_Hash       *links;     /* TODO */
-    Eina_Hash       *children;  /* stringshared values optimized hash table holding Rooms, Doors and Boards */
+    Eiotas_Iota     iota;       /**< Eiotas_Iota structural info */
+    Eina_Hash       *links;     /**< TODO */
+    Eina_Hash       *children;  /**< stringshared values optimized hash table holding Eiotas_Iotas */
 };
 
+/**
+ * @brief Free allocated resources.
+ *
+ * @param room The Eiotas_Room to free.
+ *
+ * This function will free all it's child Eiotas_Iotas.
+ */
 void eiotas_room_free(Eiotas_Room *room);
 
+/**
+ * @brief Print iota information using EINA_LOG_DBG.
+ *
+ * @param name The name of this Eiotas_Iota.
+ * @param parent The direct hierarchical parent Eiotas_Room.
+ *
+ * @return the new Eiotas_Room, @c NULL on failure
+ *
+ * This function will register the new room as a child of it's parent Eiotas_Room.
+ */
 EAPI Eiotas_Room*   eiotas_room_add(const char* name, Eiotas_Room *parent);
 
 #endif // __EIOTAS_ROOM_H__
diff --git a/src/include/eiotas_spin.h b/src/include/eiotas_spin.h
index 5f7470b..3854878 100644
--- a/src/include/eiotas_spin.h
+++ b/src/include/eiotas_spin.h
@@ -26,23 +26,77 @@
 #include <eina_inlist.h>
 #include <eina_array.h>
 
+/**
+ * @typedef Eiotas_Spin
+ * Type for a Spin, the top level Room which holds Eiotas_Particle fifos and free Eiotas_Particles.
+ */
 typedef struct _Eiotas_Spin Eiotas_Spin;
 
+/**
+ * @struct _Eiotas_Spin
+ * Struct for a Spin, the top level Room which holds Eiotas_Particle fifos and free Eiotas_Particles.
+ */
 struct  _Eiotas_Spin {
-    Eiotas_Room     room;               /* higher level Room */
-    Eina_Array      *free_particles;    /* lifo of free to reuse Particles TODO support different particle types, use an Eina_Hash */
-    Eina_Inlist     *app_fifo;          /* fifo of application priority particles */
-    Eina_Inlist     *sys_fifo;          /* fifo of system priority particles */
+    Eiotas_Room     room;               /**< higher level Room */
+    Eina_Array      *free_particles;    /**< lifo of free to reuse Eiotas_Particles TODO support different particle types, use an Eina_Hash */
+    Eina_Inlist     *app_fifo;          /**< fifo of application priority particles */
+    Eina_Inlist     *sys_fifo;          /**< fifo of system priority particles */
 };
 
+/**
+ * @brief Free allocated resources.
+ *
+ * @param spin The Eiotas_Spin to free.
+ *
+ * This function will free all it's child Iotas,
+ * all the Eiotas_Particles holded in app_fifo, sys_fifo and free_particles.
+ */
 EAPI void               eiotas_spin_free(Eiotas_Spin *spin);
 
+/**
+ * @brief Allocate the resources.
+ *
+ * @param name The name of this spin.
+ * @param step The count of pointers to add when increasing the fifo size.
+ *
+ * @return the new allocated Eiotas_Spin @c NULL on failure
+ *
+ * @see eina_array_new().
+ */
 EAPI Eiotas_Spin*       eiotas_spin_add(const char* name, unsigned int step);
 
+/**
+ * @brief Require a Eiotas_Particle from the free list.
+ *
+ * @param spin The Eiotas_Spin to require a Eiotas_Particle from.
+ *
+ * @return a ready to use Eiotas_Particle
+ *
+ * This function will allocate and initialize a new Eiotas_Particle if there is none in the free list.
+ */
 EAPI Eiotas_Particle*   eiotas_spin_require_particle(Eiotas_Spin *spin);
 
+/**
+ * @brief Release a particle.
+ *
+ * @param spin The Eiotas_Spin to restore the particle to.
+ * @param particle The Eiotas_Particle to be restored.
+ *
+ * This function calls eiotas_particle_reset() before giving back the Eiotas_Particle.
+ * Each Eiotas_Particle merged in the first one are also released.
+ *
+ * @see eiotas_particle_reset().
+ */
 EAPI void               eiotas_spin_release_particle(Eiotas_Spin *spin, Eiotas_Particle *particle);
 
+/**
+ * @brief Appand the Eiotas_Particle to the app or sys fifo.
+ *
+ * @param spin The Eiotas_Spin to post the particle to.
+ * @param particle The Eiotas_Particle to be sent.
+ * @param system Post to the system fifo us true, otherwise to the application fifo.
+ *
+ */
 EAPI void               eiotas_spin_send_particle(Eiotas_Spin *spin, Eiotas_Particle *particle, Eina_Bool system);
 
 #define eiotas_require_particle(_iota) eiotas_spin_require_particle((Eiotas_Spin*)((Eiotas_Iota*)(_iota))->spin)
diff --git a/src/include/eiotas_userbits.h b/src/include/eiotas_userbits.h
index 4e33d1e..e4149b8 100644
--- a/src/include/eiotas_userbits.h
+++ b/src/include/eiotas_userbits.h
@@ -22,30 +22,69 @@
 #include "eiotas_iota.h"
 #include "eiotas_particle.h"
 
+/**
+ * @typedef Eiotas_User_Bits
+ * Type for a Eiotas_User_Bits.
+ */
 typedef struct _Eiotas_User_Bits Eiotas_User_Bits;
 
+/**
+ * @typedef Eiotas_User_Data
+ * Struct for user allocated data attached to a Eiotas_Door or a Eiotas_Board
+ */
 typedef void Eiotas_User_Data;
 
+/**
+ * @typedef Eiotas_User_Data
+ * Type for function called on resources free
+ *
+ * @see eiotas_door_free()
+ * @see eiotas_board_free()
+ */
 typedef void (*Eiotas_User_Data_Free)   (Eiotas_User_Data*);
 
+/**
+ * @typedef Eiotas_Receive_Particle
+ * Type for function called on Eiotas_Particle receive
+ */
 typedef void (*Eiotas_Receive_Particle) (Eiotas_Iota *iota, Eiotas_Particle *particle, Eiotas_User_Data *data);
 
+/**
+ * @typedef Eiotas_Init
+ * Type for function called on systsem init
+ */
 typedef void (*Eiotas_Init)     (Eiotas_Iota *iota, Eiotas_User_Data *data);
 
+/**
+ * @typedef Eiotas_Shutdown
+ * Type for function called on system shutdown
+ */
 typedef void (*Eiotas_Shutdown) (Eiotas_Iota *iota, Eiotas_User_Data *data);
 
+/**
+ * @typedef Eiotas_Suspend
+ * Type for function called on system suspend
+ */
 typedef void (*Eiotas_Suspend)  (Eiotas_Iota *iota, Eiotas_User_Data *data);
 
+/**
+ * @typedef Eiotas_Resume
+ * Type for function called on system resume
+ */
 typedef void (*Eiotas_Resume)   (Eiotas_Iota *iota, Eiotas_User_Data *data);
 
+/**
+ * @typedef _Eiotas_User_Bits
+ * Type for a Eiotas_User_Bits.
+ */
 struct _Eiotas_User_Bits {
-    Eiotas_User_Data        *data;          /* user data */
-    Eiotas_User_Data_Free   free_fct;       /* to free user data */
-    Eiotas_Receive_Particle recv_fct;       /* to receive and process a particle */
-    Eiotas_Init             init_fct;       /* to initialize user data on system init */
-    Eiotas_Shutdown         shutdown_fct;   /* to finalize user data on system shutdown */
-    Eiotas_Suspend          suspend_fct;    /* to serialize user data on system shutdown */
-    Eiotas_Resume           resume_fct;     /* to deserialize data on system resume */
+    Eiotas_User_Data        *data;          /**< user data */
+    Eiotas_User_Data_Free   free_fct;       /**< to free user data */
+    Eiotas_Receive_Particle recv_fct;       /**< to receive and process a Eiotas_Particle */
+    Eiotas_Init             init_fct;       /**< to initialize user data on system init */
+    Eiotas_Shutdown         shutdown_fct;   /**< to finalize user data on system shutdown */
+    Eiotas_Suspend          suspend_fct;    /**< to serialize user data on system shutdown */
+    Eiotas_Resume           resume_fct;     /**< to deserialize data on system resume */
 };
 
 #endif // __EIOTAS_USERBITS_H__