1 files changed, 58 insertions, 4 deletions
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)