add main doc for eina_convert

git-svn-id: http://svn.enlightenment.org/svn/e/trunk/PROTO/eina@36187 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33

diff --git a/src/include/eina_lalloc.h b/src/include/eina_lalloc.h
index 91bdcaa..99de0fd 100644 (file)
--- a/src/include/eina_lalloc.h
+++ b/src/include/eina_lalloc.h
@@ -22,7 +22,14 @@
 #include "eina_types.h"
 
 /**
- * @defgroup Lalloc_Group Lazy allocator
+ * @addtogroup Eina_Tools_Group Tools
+ *
+ * @{
+ */
+
+/**
+ * @defgroup Eina_Lalloc_Group Lazy allocator
+ *
  * @{
  */
 
@@ -32,11 +39,18 @@ typedef void (*Eina_Lalloc_Free) (void *user_data);
 #define EINA_LALLOC_FREE(function) ((Eina_Lalloc_Free)function)
 
 typedef struct _Eina_Lalloc Eina_Lalloc;
-EAPI void eina_lalloc_delete(Eina_Lalloc *a);
+
 EAPI Eina_Lalloc *eina_lalloc_new(void *data, Eina_Lalloc_Alloc alloc_cb, Eina_Lalloc_Free free_cb, int num_init);
+EAPI void eina_lalloc_delete(Eina_Lalloc *a);
 EAPI Eina_Bool eina_lalloc_elements_add(Eina_Lalloc *a, int num);
 EAPI Eina_Bool eina_lalloc_element_add(Eina_Lalloc *a);
 
-/** @} */
+/**
+ * @}
+ */
+
+/**
+ * @}
+ */
 
-#endif
+#endif /* EINA_LALLOC_H_ */

diff --git a/src/lib/eina_convert.c b/src/lib/eina_convert.c
index ce96f01..ef9a46b 100644 (file)
--- a/src/lib/eina_convert.c
+++ b/src/lib/eina_convert.c
@@ -89,6 +89,115 @@ EAPI Eina_Error EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH = 0;
  * These functions allow you to convert integer or real numbers to
  * string or conversely.
  *
+ * To use these function, you have to call eina_convert_init()
+ * first, and eina_convert_shutdown() when they are not used anymore.
+ *
+ * @section Eina_Convert_From_Integer_To_Sring Conversion from integer to string
+ *
+ * To convert an integer to a string in the decimal base,
+ * eina_convert_itoa() should be used. If the hexadecimal base is
+ * wanted, eina_convert_xtoa() should be used. They all need a bufffer
+ * sufficiently large to store all the cyphers.
+ *
+ * Here is an exemple of use:
+ *
+ * @code
+ * #include <stdlib.h>
+ * #include <stdio.h>
+ *
+ * #include <eina_convert.h>
+ *
+ * int main(void)
+ * {
+ *    char *tmp[128];
+ *
+ *    if (!eina_convert_init())
+ *    {
+ *        printf ("Error during the initialization of eina_convert module\n");
+ *        return EXIT_FAILURE;
+ *    }
+ *
+ *    eina_convert_itoa(45, tmp);
+ *    printf("value: %s\n", tmp);
+
+ *    eina_convert_xtoa(0xA1, tmp);
+ *    printf("value: %s\n", tmp);
+ *
+ *    eina_convert_shutdown();
+ *
+ *    return EXIT_SUCCESS;
+ * }
+ * @endcode
+ *
+ * Compile this code with the following commant:
+ *
+ * @code
+ * gcc -Wall -o test_eina_convert test_eina.c `pkg-config --cflags --libs eina`
+ * @endcode
+ *
+ * @note
+ * The alphabetical cyphers are in lower case.
+ *
+ * @section Eina_Convert_Double Conversion double / string
+ *
+ * To convert a double to a string, eina_convert_dtoa() should be
+ * used. Like with the integer functions, a buffer must be used. The
+ * resulting string ghas the following format (which is the result
+ * obtained with snprintf() and the @%a modifier):
+ *
+ * @code
+ * [-]0xh.hhhhhp[+-]e
+ * @endcode
+ *
+ * To convert a string to a double, eina_convert_atod() should be
+ * used. The format of the string must be as above. Then, the double
+ * has the following mantiss and exponent:
+ *
+ * @code
+ * mantiss  : [-]hhhhhh
+ * exponent : 2^([+-]e - 4 * n)
+ * @endcode
+ *
+ * with n being number of cypers after the point in the string
+ * format. To obtain the double number from the mantiss and exponent,
+ * use ldexp().
+ *
+ * Here is an exemple of use:
+ *
+ * @code
+ * #include <stdlib.h>
+ * #include <stdio.h>
+ *
+ * #include <eina_convert.h>
+ *
+ * int main(void)
+ * {
+ *    char     *tmp[128];
+ *    long long int m = 0;
+ *    long int  e = 0;
+ *    doule     r;
+ *
+ *    if (!eina_convert_init())
+ *    {
+ *        printf ("Error during the initialization of eina_convert module\n");
+ *        return EXIT_FAILURE;
+ *    }
+ *
+ *    eina_convert_dtoa(40.56, tmp);
+ *    printf("value: %s\n", tmp);
+
+ *    eina_convert_atod(tmp, 128, &m, &e);
+ *    r = ldexp((double)m, e);
+ *    printf("value: %s\n", tmp);
+ *
+ *    eina_convert_shutdown();
+ *
+ *    return EXIT_SUCCESS;
+ * }
+ * @endcode
+ *
+ * Compile this code with the same command as above.
+ *
  * @{
  */
 
@@ -195,8 +304,9 @@ eina_convert_itoa(int n, char *s)
  * character.
  *
  * This function converts @p n to a nul terminated string. The
- * converted string is in hexadecimal base. As no check is done, @p s
- * must be a buffer that is sufficiently large to store the integer.
+ * converted string is in hexadecimal base and the alphabetical
+ * cyphers are in lower case. As no check is done, @p s must be a
+ * buffer that is sufficiently large to store the integer.
  *
  * The returned value is the length os the string, including the nul
  * terminated character.

diff --git a/src/lib/eina_lalloc.c b/src/lib/eina_lalloc.c
index c78e92f..50f5699 100644 (file)
--- a/src/lib/eina_lalloc.c
+++ b/src/lib/eina_lalloc.c
@@ -29,6 +29,10 @@
  *                                  Local                                     *
  *============================================================================*/
 
+/**
+ * @cond LOCAL
+ */
+
 struct _Eina_Lalloc
 {
        void    *data;
@@ -39,6 +43,10 @@ struct _Eina_Lalloc
        Eina_Lalloc_Free free_cb;
 };
 
+/**
+ * @endcond
+ */
+
 /*============================================================================*
  *                                 Global                                     *
  *============================================================================*/
@@ -48,9 +56,11 @@ struct _Eina_Lalloc
  *============================================================================*/
 
 /**
- * To be documented
- * FIXME: To be fixed
+ * @addtogroup Eina_Lalloc_Group Lazy allocator
+ *
+ * @{
  */
+
 EAPI Eina_Lalloc * eina_lalloc_new(void *data, Eina_Lalloc_Alloc alloc_cb, Eina_Lalloc_Free free_cb, int num_init)
 {
        Eina_Lalloc *a;
@@ -67,10 +77,12 @@ EAPI Eina_Lalloc * eina_lalloc_new(void *data, Eina_Lalloc_Alloc alloc_cb, Eina_
        return a;
 }
 
-/**
- * To be documented
- * FIXME: To be fixed
- */
+EAPI void eina_lalloc_delete(Eina_Lalloc *a)
+{
+       a->free_cb(a->data);
+       free(a);
+}
+
 EAPI Eina_Bool eina_lalloc_element_add(Eina_Lalloc *a)
 {
        if (a->num_elements == a->num_allocated)
@@ -88,10 +100,6 @@ EAPI Eina_Bool eina_lalloc_element_add(Eina_Lalloc *a)
        return EINA_TRUE;
 }
 
-/**
- * To be documented
- * FIXME: To be fixed
- */
 EAPI Eina_Bool eina_lalloc_elements_add(Eina_Lalloc *a, int num)
 {
        int tmp;
@@ -125,11 +133,5 @@ EAPI Eina_Bool eina_lalloc_elements_add(Eina_Lalloc *a, int num)
 }
 
 /**
- * To be documented
- * FIXME: To be fixed
+ * @}
  */
-EAPI void eina_lalloc_delete(Eina_Lalloc *a)
-{
-       a->free_cb(a->data);
-       free(a);
-}