Add documentation for xbt_dict_foreach

[simgrid.git] / include / xbt / dict.h

diff --git a/include/xbt/dict.h b/include/xbt/dict.h
index 5c6f6df..1dc5685 100644 (file)
--- a/include/xbt/dict.h
+++ b/include/xbt/dict.h
@@ -91,12 +91,12 @@ XBT_PUBLIC(void *) xbt_dict_get_or_null_ext(xbt_dict_t dict,
 XBT_PUBLIC(void) xbt_dict_remove_ext(xbt_dict_t dict, const char *key,
                                      int key_len);
 
-
+#ifdef XBT_USE_DEPRECATED
 XBT_PUBLIC(void) xbt_dicti_set(xbt_dict_t dict, uintptr_t key,
                                uintptr_t data);
 XBT_PUBLIC(uintptr_t) xbt_dicti_get(xbt_dict_t dict, uintptr_t key);
 XBT_PUBLIC(void) xbt_dicti_remove(xbt_dict_t dict, uintptr_t key);
-
+#endif
 
 /** @} */
 /** @defgroup XBT_dict_curs Cursors on dictionaries
@@ -139,14 +139,32 @@ XBT_PUBLIC(void) xbt_dict_cursor_first(const xbt_dict_t dict,
 XBT_PUBLIC(void) xbt_dict_cursor_step(xbt_dict_cursor_t cursor);
 XBT_PUBLIC(int) xbt_dict_cursor_get_or_free(xbt_dict_cursor_t * cursor,
                                             char **key, void **data);
-  /** @def xbt_dict_foreach
-      @hideinitializer */
+/** @def xbt_dict_foreach
+ *  @param dict a \ref xbt_dict_t iterator
+ *  @param cursor an \ref xbt_dict_cursor_t used as cursor
+ *  @param key a char*
+ *  @param data a void** output
+ *  @hideinitializer
+ *
+ * \note An example of usage:
+ * \code
+xbt_dict_cursor_t cursor = NULL;
+char *key;
+char *data;
+
+xbt_dict_foreach(head, cursor, key, data) {
+ printf("Key %s with data %s\n",key,data);
+}
+\endcode
+ */
 #  define xbt_dict_foreach(dict,cursor,key,data)                       \
     for (cursor=NULL, xbt_dict_cursor_first((dict),&(cursor)) ;        \
          xbt_dict_cursor_get_or_free(&(cursor),(char**)&(key),(void**)(&data));\
          xbt_dict_cursor_step(cursor) )
 
 /** @} */
+
+#ifdef XBT_USE_DEPRECATED
 /** @defgroup XBT_dict_multi Multi-level dictionaries
  *  @ingroup XBT_dict
  *
@@ -160,12 +178,6 @@ XBT_PUBLIC(int) xbt_dict_cursor_get_or_free(xbt_dict_cursor_t * cursor,
  * @{
  */
 
-/** \brief To dump multicache, this function dumps a cache                           */
-XBT_PUBLIC(void) xbt_dict_print(void *data);
-/** \brief To dump multicache, this one dumps a string                               */
-XBT_PUBLIC(void) xbt_dict_prints(void *data);
-
-
 /*----[ xbt_multidict_set ]--------------------------------------------------*/
 XBT_PUBLIC(void)
 xbt_multidict_set(xbt_dict_t mdict,
@@ -189,6 +201,7 @@ XBT_PUBLIC(void) xbt_multidict_remove_ext(xbt_dict_t mdict,
                                           xbt_dynar_t lens);
 
 /** @} */
+#endif
 
 SG_END_DECL()
 #endif                          /* _XBT_DICT_H */