* update the doc of stringshre

 * fix minor warnings from doxygen

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

diff --git a/src/include/eina_stringshare.h b/src/include/eina_stringshare.h
index d69f5ea..83cdbfe 100644 (file)
--- a/src/include/eina_stringshare.h
+++ b/src/include/eina_stringshare.h
@@ -54,7 +54,8 @@
 #include "eina_types.h"
 
 /**
- * @defgroup Stringshare_Group Shared strings.
+ * @defgroup Eina_Stringshare_Group String Instance Functions
+ *
  * @{
  */
 
@@ -63,6 +64,8 @@ EAPI int eina_stringshare_shutdown(void);
 EAPI const char *eina_stringshare_add(const char *str);
 EAPI void eina_stringshare_del(const char *str);
 
-/** @} */
+/**
+ * @}
+ */
 
 #endif /* EINA_STRINGSHARE_H_ */

diff --git a/src/lib/eina_accessor.c b/src/lib/eina_accessor.c
index 7609381..28719c2 100644 (file)
--- a/src/lib/eina_accessor.c
+++ b/src/lib/eina_accessor.c
@@ -43,7 +43,7 @@
  */
 
 /**
- * @addtogroup Eina_Accessor_Group Accessors Functions
+ * @addtogroup Eina_Accessor_Group Accessor Functions
  *
  * @brief These functions manage accessor on containers.
  *

diff --git a/src/lib/eina_iterator.c b/src/lib/eina_iterator.c
index b2ca008..e36a030 100644 (file)
--- a/src/lib/eina_iterator.c
+++ b/src/lib/eina_iterator.c
@@ -43,7 +43,7 @@
  */
 
 /**
- * @addtogroup Eina_Iterator_Group Iterators Functions
+ * @addtogroup Eina_Iterator_Group Iterator Functions
  *
  * @brief These functions manage iterators on containers.
  *

diff --git a/src/lib/eina_stringshare.c b/src/lib/eina_stringshare.c
index 0875bec..753f8ac 100644 (file)
--- a/src/lib/eina_stringshare.c
+++ b/src/lib/eina_stringshare.c
@@ -51,6 +51,14 @@
  *  CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
+
+/**
+ * @page tutorial_stringshare_page Stringshare Tutorial
+ *
+ * to be written...
+ *
+ */
+
 #ifdef HAVE_CONFIG_H
 # include "config.h"
 #endif
@@ -69,6 +77,10 @@
  *                                  Local                                     *
  *============================================================================*/
 
+/**
+ * @cond LOCAL
+ */
+
 typedef struct _Eina_Stringshare             Eina_Stringshare;
 typedef struct _Eina_Stringshare_Node        Eina_Stringshare_Node;
 typedef struct _Eina_Stringshare_Head        Eina_Stringshare_Head;
@@ -111,6 +123,11 @@ _eina_stringshare_node(const Eina_Stringshare_Head *left, const Eina_Stringshare
    return EINA_RBTREE_RIGHT;
 }
 
+/**
+ * @endcond
+ */
+
+
 /*============================================================================*
  *                                 Global                                     *
  *============================================================================*/
@@ -138,12 +155,20 @@ _eina_stringshare_node(const Eina_Stringshare_Head *left, const Eina_Stringshare
  * string creation/destruction speed, reduces memory use and decreases
  * memory fragmentation, so a win all-around.
  *
+ * For more information, you can look at the @ref tutorial_stringshare_page.
+ *
  * @{
  */
 
 /**
- * Initialize the eina stringshare internal structure.
- * @return  Zero on failure, non-zero on successful initialization.
+ * @brief Initialize the eina stringshare internal structure.
+ *
+ * @return 1 or greater on success, 0 on error.
+ *
+ * This function allocates the memory needed by the stringshare
+ * internal structure and sets up the error module or Eina. It is also
+ * called by eina_init(). It returns 0 on failure, otherwise it
+ * returns the number of times it has already been called.
  */
 EAPI int
 eina_stringshare_init()
@@ -165,10 +190,66 @@ eina_stringshare_init()
 }
 
 /**
- * Retrieves an instance of a string for use in a program.
+ * @brief Shut down the eina stringshare internal structures
+ *
+ * @return 0 when the stringshare module is completely shut down, 1 or
+ * greater otherwise.
+ *
+ * This function frees the memory allocated by eina_stringshare_init()
+ * and shut down the error module. It is also called by
+ * eina_shutdown(). It returns 0 when it is called the same number of
+ * times than eina_stringshare_init().
+ */
+EAPI int
+eina_stringshare_shutdown()
+{
+   --_eina_stringshare_init_count;
+   if (!_eina_stringshare_init_count)
+     {
+       int i;
+       /* remove any string still in the table */
+       for (i = 0; i < 256; i++)
+         {
+            Eina_Stringshare_Head *ed = share->buckets[i];
+            Eina_Stringshare_Head *save;
+
+            while (ed)
+              {
+                 save = ed;
+                 ed = (Eina_Stringshare_Head*) eina_rbtree_inline_remove(&ed->node, &ed->node,
+                                                                         EINA_RBTREE_CMP_NODE_CB(_eina_stringshare_node), NULL);
+                 while (save->head)
+                   {
+                      Eina_Stringshare_Node *el = save->head;
+
+                      save->head = el->next;
+                      free(el);
+                   }
+                 free(save);
+              }
+            share->buckets[i] = NULL;
+         }
+       free(share);
+       share = NULL;
+
+       eina_error_shutdown();
+     }
+
+   return _eina_stringshare_init_count;
+}
+
+/**
+ * @brief Retrieve an instance of a string for use in a program.
+ *
  * @param   str The string to retrieve an instance of.
  * @return  A pointer to an instance of the string on success.
  *          @c NULL on failure.
+ *
+ * This function retrieves an instance of @p str. If @p str is
+ * @c NULL, then @c NULL is returned. If @p str is already stored, it
+ * is just returned and its reference counter is increased. Otherwise
+ * it is added to the strings to be searched and a duplicated string
+ * of @p str is returned.
  */
 EAPI const char *
 eina_stringshare_add(const char *str)
@@ -224,11 +305,14 @@ eina_stringshare_add(const char *str)
 }
 
 /**
- * Notes that the given string has lost an instance.
- *
- * It will free the string if no other instances are left.
+ * @brief Note that the given string has lost an instance.
  *
  * @param str string The given string.
+ *
+ * This function decreases the reference counter associated to @p str
+ * if it exists. If that counter reaches 0, the memory associated to
+ * @p str is freed. If @p str is NULL, the function returns
+ * immediatly.
  */
 EAPI void
 eina_stringshare_del(const char *str)
@@ -280,46 +364,5 @@ eina_stringshare_del(const char *str)
 }
 
 /**
- * Shutdown the eina string internal structures
- */
-EAPI int
-eina_stringshare_shutdown()
-{
-   --_eina_stringshare_init_count;
-   if (!_eina_stringshare_init_count)
-     {
-       int i;
-       /* remove any string still in the table */
-       for (i = 0; i < 256; i++)
-         {
-            Eina_Stringshare_Head *ed = share->buckets[i];
-            Eina_Stringshare_Head *save;
-
-            while (ed)
-              {
-                 save = ed;
-                 ed = (Eina_Stringshare_Head*) eina_rbtree_inline_remove(&ed->node, &ed->node,
-                                                                         EINA_RBTREE_CMP_NODE_CB(_eina_stringshare_node), NULL);
-                 while (save->head)
-                   {
-                      Eina_Stringshare_Node *el = save->head;
-
-                      save->head = el->next;
-                      free(el);
-                   }
-                 free(save);
-              }
-            share->buckets[i] = NULL;
-         }
-       free(share);
-       share = NULL;
-
-       eina_error_shutdown();
-     }
-
-   return _eina_stringshare_init_count;
-}
-
-/**
  * @}
  */