documentation

9 files changed, 186 insertions, 61 deletions

diff --git a/src/include/eiotas_board.h b/src/include/eiotas_board.h
index 6572faf..9f8d5ef 100644
--- a/src/include/eiotas_board.h
+++ b/src/include/eiotas_board.h
@@ -42,9 +42,19 @@ struct _Eiotas_Board {
 };
 
 /**
+ * @defgroup Eiotas_Board Eiotas_Board
+ *
+ * A Eiota_Board holds @ref Eiotas_Particle received.
+ * When two @ref Eiotas_Particle with the same link_value exists, they are merged together
+ * and delivered to user code through Eiotas_Receive_Particle callback.
+ *
+ * @{
+ */
+
+/**
  * @brief Free allocated resources.
  *
- * @param board The Eiotas_Board to free.
+ * @param board The @ref Eiotas_Board to free.
  *
  * This function will free all it's user data using user_bits ... FIXME
  */
@@ -54,13 +64,17 @@ 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 parent The direct hierarchical parent @ref Eiotas_Room.
  * @param user_bits A Eiotas_User_Bits initilized with user side pointers.
  *
- * @return the new allocated Eiotas_Board @c NULL on failure
+ * @return the new allocated @ref 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 318779f..d136c1a 100644
--- a/src/include/eiotas_door.h
+++ b/src/include/eiotas_door.h
@@ -41,9 +41,19 @@ struct _Eiotas_Door {
 };
 
 /**
+ * @defgroup Eiotas_Door Eiotas_Door
+ *
+ * A Eiota_Door is the main structure used to interact with user code.
+ * @ref Eiotas_Particle sent to user code are, follower and sent releaseed
+ * through eiotas_spin_release_particle if not cprrectly managed by user code.
+ *
+ * @{
+ */
+
+/**
  * @brief Free allocated resources.
  *
- * @param door The Eiotas_Door to free.
+ * @param door The @ref Eiotas_Door to free.
  *
  * This function will free all it's user data using user_bits ... FIXME
  */
@@ -53,13 +63,17 @@ 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 parent The direct hierarchical parent @ref Eiotas_Room.
  * @param user_bits A Eiotas_User_Bits initilized with user side pointers.
  *
- * @return the new allocated Eiotas_Door @c NULL on failure
+ * @return the new allocated @ref 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 d54ae61..36ce1cc 100644
--- a/src/include/eiotas_iota.h
+++ b/src/include/eiotas_iota.h
@@ -46,29 +46,51 @@ typedef struct _Eiotas_Iota Eiotas_Iota;
  */
 struct _Eiotas_Iota {
     Eiotas_Type         type;       /**< type of the iota */
-    Eiotas_Iota         *spin;      /**< top level iota which is a Eiotas_Spin */
+    Eiotas_Iota         *spin;      /**< top level iota which is a @ref 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 */
+    Eina_Stringshare    *path;      /**< full path to this @ref Eiotas_Iota */
 };
 
 /**
+ * @defgroup Eiotas_Iota Eiotas_Iota
+ *
+ * This is the structural info stored in each @ref Eiotas_Room, @ref Eiotas_Door, @ref Eiotas_Board
+ *
+ * @{
+ */
+
+/**
  * @brief Print iota information using EINA_LOG_DBG.
  *
- * @param iota The Eiotas_Iota to show.
+ * @param iota The @ref Eiotas_Iota to show.
  */
 EAPI void eiotas_iota_show(Eiotas_Iota *iota);
 
 /**
  * @brief Free allocated resources.
  *
- * @param iota The Eiotas_Iota to free.
+ * @param iota The @ref Eiotas_Iota to free.
  *
  */
 void eiotas_iota_free(Eiotas_Iota *iota);
 
+/**
+ * @brief Require a @ref Eiotas_Particle from the free list.
+ *
+ * @see eiotas_spin_require_particle
+ */
 #define eiotas_iota_require_particle(_iota) eiotas_spin_require_particle((Eiotas_Spin*)(_iota)->spin)
 
+/**
+ * @brief Release a particle.
+ *
+ * @see eiotas_spin_release_particle
+ */
 #define eiotas_iota_release_particle(_iota,_particle) eiotas_spin_release_particle((Eiotas_Spin*)(_iota)->spin,_particle)
 
+/**
+ * @}
+ */
+
 #endif // __EIOTAS_IOTA_H__
diff --git a/src/include/eiotas_link.h b/src/include/eiotas_link.h
index 4cc4e44..2d10300 100644
--- a/src/include/eiotas_link.h
+++ b/src/include/eiotas_link.h
@@ -21,22 +21,34 @@
 
 /**
  * @typedef Eiotas_Link
- * Type for a Link between Eiotas_Iotas.
+ * Type for a Link between @ref Eiotas_Iota.
  */
 typedef struct _Eiotas_Link Eiotas_Link;
 
 /**
  * @struct _Eiotas_Link
- * Struct for a Link between Eiotas_Iotas.
+ * Struct for a Link between @ref Eiotas_Iota.
  */
 struct _Eiotas_Link {
 };
 
 /**
+ * @defgroup Eiotas_Link Eiotas_Link
+ *
+ * A Eiota_Link allows to apply a destination list to a @ref Eiotas_Particle with no defined destination.
+ *
+ * @{
+ */
+
+/**
  * @brief Free allocated resources.
  *
- * @param link The Eiotas_Link to free.
+ * @param link The @ref 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 d75ab96..75ac6fe 100644
--- a/src/include/eiotas_main.h
+++ b/src/include/eiotas_main.h
@@ -23,20 +23,32 @@
 
 /**
  * @typedef Eiotas_Version
- * The version of Eiotas.
+ * Type for the version of Eiotas.
  */
-typedef struct _Eiotas_Version
+typedef struct _Eiotas_Version Eiotas_Version;
+
+/**
+ * @struct _Eiotas_Version
+ * Struct version of Eiotas.
+ */
+struct _Eiotas_Version
 {
    int major;    /**< Major component of the version */
    int minor;    /**< Minor component of the version */
    int micro;    /**< Micro component of the version */
-} Eiotas_Version;
+};
 
 EAPI extern Eiotas_Version *eiotas_version;
 
 EAPI extern int _eiotas_log_dom;
 
 /**
+ * @defgroup Eiotas_Main Eiotas
+ *
+ * @{
+ */
+
+/**
  * @brief Initialize the Eiotas library.
  *
  * @return 1 or greater on success, 0 on error.
@@ -67,4 +79,8 @@ EAPI int eiotas_init();
  */
 EAPI int eiotas_shutdown();
 
+/**
+ * @}
+ */
+
 #endif // __EIOTAS_MAIN_H__
diff --git a/src/include/eiotas_particle.h b/src/include/eiotas_particle.h
index 3f74040..5ea2215 100644
--- a/src/include/eiotas_particle.h
+++ b/src/include/eiotas_particle.h
@@ -50,52 +50,64 @@ struct _Eiotas_Particle {
 };
 
 /**
+ * @defgroup Eiotas_Particle Eiotas_Particle
+ *
+ * The central part of Eiotas. The Particle holds, the data, the destination list.
+ *
+ * @{
+ */
+
+/**
  * @brief Free allocated resources.
  *
- * @param particle The Eiotas_Particle to free.
+ * @param particle The @ref Eiotas_Particle to free.
  *
- * This function will free all the merged Eiotas_Particle
+ * This function will free all the merged @ref Eiotas_Particle
  */
 void eiotas_particle_free(Eiotas_Particle *particle);
 
 /**
  * @brief Allocate the resources.
  *
- * @return the new allocated Eiotas_Particle @c NULL on failure
+ * @return the new allocated @ref Eiotas_Particle @c NULL on failure
  */
 Eiotas_Particle* eiotas_particle_alloc();
 
 /**
- * @brief Reset the Eiotas_Particle so that it can be required later.
+ * @brief Reset the @ref Eiotas_Particle so that it can be required later.
  *
- * @param particle The Eiotas_Particle to reset
+ * @param particle The @ref 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
+ * @param particle The @ref Eiotas_Particle to init
+ * @param iota The @ref 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
+ * @param particle The @ref Eiotas_Particle to hold @p p
+ * @param p The @ref 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
+ * @brief Add destinations to the @ref Eiotas_Particle
  *
- * @param particle The Eiotas_Particle to add destinations to
+ * @param particle The @ref 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.
+ * This function will append each destination found to the destination list of the @ref 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 644dc0e..c265344 100644
--- a/src/include/eiotas_room.h
+++ b/src/include/eiotas_room.h
@@ -25,39 +25,51 @@
 
 /**
  * @typedef Eiotas_Room
- * Type for a Room, which holds other child Eiotas_Iotas.
+ * Type for a Room, which holds other child @ref Eiotas_Iota.
  */
 typedef struct _Eiotas_Room Eiotas_Room;
 
 /**
  * @struct _Eiotas_Room
- * Struct for a Room, which holds other child Eiotas_Iotas.
+ * Struct for a Room, which holds other child @ref Eiotas_Iota.
  */
 struct _Eiotas_Room {
-    Eiotas_Iota     iota;       /**< Eiotas_Iota structural info */
+    Eiotas_Iota     iota;       /**< @ref Eiotas_Iota structural info */
     Eina_Hash       *links;     /**< TODO */
-    Eina_Hash       *children;  /**< stringshared values optimized hash table holding Eiotas_Iotas */
+    Eina_Hash       *children;  /**< stringshared values optimized hash table holding @ref Eiotas_Iota */
 };
 
 /**
+ * @defgroup Eiotas_Room Eiotas_Room
+ *
+ * A Eiota_Room may hold children @ref Eiotas_Room or @ref Eiotas_Door (@ref Eiotas_Board).
+ *
+ * @{
+ */
+
+/**
  * @brief Free allocated resources.
  *
- * @param room The Eiotas_Room to free.
+ * @param room The @ref Eiotas_Room to free.
  *
- * This function will free all it's child Eiotas_Iotas.
+ * This function will free all it's child @ref Eiotas_Iota.
  */
 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.
+ * @param name The name of this @ref Eiotas_Iota.
+ * @param parent The direct hierarchical parent @ref Eiotas_Room.
  *
- * @return the new Eiotas_Room, @c NULL on failure
+ * @return the new @ref Eiotas_Room, @c NULL on failure
  *
- * This function will register the new room as a child of it's parent Eiotas_Room.
+ * This function will register the new room as a child of it's parent @ref 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 3854878..08742e4 100644
--- a/src/include/eiotas_spin.h
+++ b/src/include/eiotas_spin.h
@@ -28,28 +28,37 @@
 
 /**
  * @typedef Eiotas_Spin
- * Type for a Spin, the top level Room which holds Eiotas_Particle fifos and free Eiotas_Particles.
+ * Type for a Spin, the top level Room which holds @ref Eiotas_Particle fifos and free @ref Eiotas_Particle.
  */
 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 for a Spin, the top level Room which holds @ref Eiotas_Particle fifos and free @ref Eiotas_Particle.
  */
 struct  _Eiotas_Spin {
     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_Array      *free_particles;    /**< lifo of free to reuse @ref Eiotas_Particle 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 */
 };
 
 /**
+ * @defgroup Eiotas_Spin Eiotas_Spin
+ *
+ * A Eiota_Spin is the top level object. It holds @ref Eiotas_Particle free list,
+ * @ref Eiotas_Particle system and application fifos.
+ *
+ * @{
+ */
+
+/**
  * @brief Free allocated resources.
  *
- * @param spin The Eiotas_Spin to free.
+ * @param spin The @ref 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.
+ * all the @ref Eiotas_Particle holded in app_fifo, sys_fifo and free_particles.
  */
 EAPI void               eiotas_spin_free(Eiotas_Spin *spin);
 
@@ -59,48 +68,62 @@ EAPI void               eiotas_spin_free(Eiotas_Spin *spin);
  * @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
+ * @return the new allocated @ref 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.
+ * @brief Require a @ref Eiotas_Particle from the free list.
  *
- * @param spin The Eiotas_Spin to require a Eiotas_Particle from.
+ * @param spin The @ref Eiotas_Spin to require a @ref Eiotas_Particle from.
  *
- * @return a ready to use Eiotas_Particle
+ * @return a ready to use @ref Eiotas_Particle
  *
- * This function will allocate and initialize a new Eiotas_Particle if there is none in the free list.
+ * This function will allocate and initialize a new @ref 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.
+ * @param spin The @ref Eiotas_Spin to restore the particle to.
+ * @param particle The @ref 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.
+ * This function calls eiotas_particle_reset() before giving back the @ref Eiotas_Particle.
+ * Each @ref 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.
+ * @brief Append the @ref 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 spin The @ref Eiotas_Spin to post the particle to.
+ * @param particle The @ref 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);
 
+/**
+ * @brief Require a @ref Eiotas_Particle from the free list.
+ *
+ * @see eiotas_spin_require_particle
+ */
 #define eiotas_require_particle(_iota) eiotas_spin_require_particle((Eiotas_Spin*)((Eiotas_Iota*)(_iota))->spin)
 
+/**
+ * @brief Release a particle.
+ *
+ * @see eiotas_spin_release_particle
+ */
 #define eiotas_release_particle(_iota,_particle) eiotas_spin_release_particle((Eiotas_Spin*)((Eiotas_Iota*)(_iota))->spin,_particle)
 
+/**
+ * @}
+ */
+
 #endif // __EIOTAS_SPIN_H__
diff --git a/src/include/eiotas_userbits.h b/src/include/eiotas_userbits.h
index e4149b8..b48c7c2 100644
--- a/src/include/eiotas_userbits.h
+++ b/src/include/eiotas_userbits.h
@@ -24,13 +24,13 @@
 
 /**
  * @typedef Eiotas_User_Bits
- * Type for a Eiotas_User_Bits.
+ * Type for a @ref 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
+ * Struct for user allocated data attached to a @ref Eiotas_Door or a @ref Eiotas_Board
  */
 typedef void Eiotas_User_Data;
 
@@ -45,7 +45,7 @@ typedef void (*Eiotas_User_Data_Free)   (Eiotas_User_Data*);
 
 /**
  * @typedef Eiotas_Receive_Particle
- * Type for function called on Eiotas_Particle receive
+ * Type for function called on @ref Eiotas_Particle receive
  */
 typedef void (*Eiotas_Receive_Particle) (Eiotas_Iota *iota, Eiotas_Particle *particle, Eiotas_User_Data *data);
 
@@ -74,13 +74,13 @@ typedef void (*Eiotas_Suspend)  (Eiotas_Iota *iota, Eiotas_User_Data *data);
 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
+ * Struct 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 Eiotas_Particle */
+    Eiotas_Receive_Particle recv_fct;       /**< to receive and process a @ref 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 */