-misc doxygen fixes

1 files changed, 198 insertions, 86 deletions

diff --git a/src/include/gnunet_container_lib.h b/src/include/gnunet_container_lib.h
index c0aa176c5..a808c52a6 100644
--- a/src/include/gnunet_container_lib.h
+++ b/src/include/gnunet_container_lib.h
@@ -1,10 +1,10 @@
 /*
      This file is part of GNUnet.
-     (C) 2001, 2002, 2003, 2004, 2005, 2006, 2008, 2009, 2010 Christian Grothoff (and other contributing authors)
+     (C) 2001-2013 Christian Grothoff (and other contributing authors)
 
      GNUnet is free software; you can redistribute it and/or modify
      it under the terms of the GNU General Public License as published
-     by the Free Software Foundation; either version 2, or (at your
+     by the Free Software Foundation; either version 3, or (at your
      option) any later version.
 
      GNUnet is distributed in the hope that it will be useful, but
@@ -21,9 +21,13 @@
 /**
  * @file include/gnunet_container_lib.h
  * @brief container classes for GNUnet
- *
  * @author Christian Grothoff
  * @author Nils Durner
+ * @defgroup hashmap multi hash-map
+ * @defgroup heap min- or max-heap with arbitrary element removal
+ * @defgroup bloomfilter Bloom filter (probabilistic set tests)
+ * @defgroup dll Doubly-linked list
+ * @defgroup metadata Meta data (GNU libextractor key-value pairs)
  */
 
 #ifndef GNUNET_CONTAINER_LIB_H
@@ -51,28 +55,31 @@ extern "C"
 
 /**
  * @brief bloomfilter representation (opaque)
+ * @ingroup bloomfilter
  */
 struct GNUNET_CONTAINER_BloomFilter;
 
 /**
- * Iterator over HashCodes.
+ * @ingroup bloomfilter
+ * Iterator over struct GNUNET_HashCodes.
  *
  * @param cls closure
  * @param next set to the next hash code
- * @return GNUNET_YES if next was updated
- *         GNUNET_NO if there are no more entries
+ * @return #GNUNET_YES if next was updated
+ *         #GNUNET_NO if there are no more entries
  */
 typedef int (*GNUNET_HashCodeIterator) (void *cls, struct GNUNET_HashCode * next);
 
 
 /**
- * Load a bloom-filter from a file.
+ * @ingroup bloomfilter
+ * Load a Bloom filter from a file.
  *
  * @param filename the name of the file (or the prefix)
  * @param size the size of the bloom-filter (number of
  *        bytes of storage space to use); will be rounded up
  *        to next power of 2
- * @param k the number of GNUNET_CRYPTO_hash-functions to apply per
+ * @param k the number of #GNUNET_CRYPTO_hash-functions to apply per
  *        element (number of bits set per element in the set)
  * @return the bloomfilter
  */
@@ -82,15 +89,16 @@ GNUNET_CONTAINER_bloomfilter_load (const char *filename, size_t size,
 
 
 /**
- * Create a bloom filter from raw bits.
+ * @ingroup bloomfilter
+ * Create a Bloom filter from raw bits.
  *
  * @param data the raw bits in memory (maybe NULL,
  *        in which case all bits should be considered
  *        to be zero).
  * @param size the size of the bloom-filter (number of
- *        bytes of storage space to use); also size of data
+ *        bytes of storage space to use); also size of @a data
  *        -- unless data is NULL.  Must be a power of 2.
- * @param k the number of GNUNET_CRYPTO_hash-functions to apply per
+ * @param k the number of #GNUNET_CRYPTO_hash-functions to apply per
  *        element (number of bits set per element in the set)
  * @return the bloomfilter
  */
@@ -100,12 +108,13 @@ GNUNET_CONTAINER_bloomfilter_init (const char *data, size_t size,
 
 
 /**
- * Copy the raw data of this bloomfilter into
+ * @ingroup bloomfilter
+ * Copy the raw data of this Bloom filter into
  * the given data array.
  *
  * @param data where to write the data
- * @param size the size of the given data array
- * @return GNUNET_SYSERR if the data array of the wrong size
+ * @param size the size of the given @a data array
+ * @return #GNUNET_SYSERR if the data array of the wrong size
  */
 int
 GNUNET_CONTAINER_bloomfilter_get_raw_data (const struct
@@ -114,10 +123,12 @@ GNUNET_CONTAINER_bloomfilter_get_raw_data (const struct
 
 
 /**
+ * @ingroup bloomfilter
  * Test if an element is in the filter.
+ *
  * @param e the element
  * @param bf the filter
- * @return GNUNET_YES if the element is in the filter, GNUNET_NO if not
+ * @return #GNUNET_YES if the element is in the filter, #GNUNET_NO if not
  */
 int
 GNUNET_CONTAINER_bloomfilter_test (const struct GNUNET_CONTAINER_BloomFilter
@@ -125,7 +136,9 @@ GNUNET_CONTAINER_bloomfilter_test (const struct GNUNET_CONTAINER_BloomFilter
 
 
 /**
- * Add an element to the filter
+ * @ingroup bloomfilter
+ * Add an element to the filter.
+ *
  * @param bf the filter
  * @param e the element
  */
@@ -135,7 +148,9 @@ GNUNET_CONTAINER_bloomfilter_add (struct GNUNET_CONTAINER_BloomFilter *bf,
 
 
 /**
+ * @ingroup bloomfilter
  * Remove an element from the filter.
+ *
  * @param bf the filter
  * @param e the element to remove
  */
@@ -145,6 +160,7 @@ GNUNET_CONTAINER_bloomfilter_remove (struct GNUNET_CONTAINER_BloomFilter *bf,
 
 
 /**
+ * @ingroup bloomfilter
  * Create a copy of a bloomfilter.
  *
  * @param bf the filter
@@ -157,9 +173,11 @@ GNUNET_CONTAINER_bloomfilter_copy (const struct GNUNET_CONTAINER_BloomFilter
 
 
 /**
+ * @ingroup bloomfilter
  * Free the space associcated with a filter
  * in memory, flush to drive if needed (do not
- * free the space on the drive)
+ * free the space on the drive).
+ *
  * @param bf the filter
  */
 void
@@ -167,6 +185,7 @@ GNUNET_CONTAINER_bloomfilter_free (struct GNUNET_CONTAINER_BloomFilter *bf);
 
 
 /**
+ * @ingroup bloomfilter
  * Get size of the bloom filter.
  *
  * @param bf the filter
@@ -178,52 +197,58 @@ GNUNET_CONTAINER_bloomfilter_get_size (const struct GNUNET_CONTAINER_BloomFilter
 
 
 /**
- * Reset a bloom filter to empty.
+ * @ingroup bloomfilter
+ * Reset a Bloom filter to empty.
+ *
  * @param bf the filter
  */
 void
 GNUNET_CONTAINER_bloomfilter_clear (struct GNUNET_CONTAINER_BloomFilter *bf);
 
+
 /**
- * Or the entries of the given raw data array with the
- * data of the given bloom filter.  Assumes that
- * the size of the data array and the current filter
+ * @ingroup bloomfilter
+ * "or" the entries of the given raw data array with the
+ * data of the given Bloom filter.  Assumes that
+ * the @a size of the @a data array and the current filter
  * match.
  *
  * @param bf the filter
  * @param data data to OR-in
- * @param size size of data
- * @return GNUNET_OK on success
+ * @param size size of @a data
+ * @return #GNUNET_OK on success
  */
 int
 GNUNET_CONTAINER_bloomfilter_or (struct GNUNET_CONTAINER_BloomFilter *bf,
                                  const char *data, size_t size);
 
+
 /**
- * Or the entries of the given raw data array with the
- * data of the given bloom filter.  Assumes that
- * the size of the data array and the current filter
- * match.
+ * @ingroup bloomfilter
+ * "or" the entries of the given raw data array with the
+ * data of the given Bloom filter.  Assumes that
+ * the size of the two filters matches.
  *
  * @param bf the filter
  * @param to_or the bloomfilter to or-in
- * @param size number of bytes in data
+ * @return #GNUNET_OK on success
  */
 int
 GNUNET_CONTAINER_bloomfilter_or2 (struct GNUNET_CONTAINER_BloomFilter *bf,
                                   const struct GNUNET_CONTAINER_BloomFilter
-                                  *to_or, size_t size);
+                                  *to_or);
 
 /**
+ * @ingroup bloomfilter
  * Resize a bloom filter.  Note that this operation
- * is pretty costly.  Essentially, the bloom filter
+ * is pretty costly.  Essentially, the Bloom filter
  * needs to be completely re-build.
  *
  * @param bf the filter
  * @param iterator an iterator over all elements stored in the BF
- * @param iterator_cls closure for iterator
+ * @param iterator_cls closure for @a iterator
  * @param size the new size for the filter
- * @param k the new number of GNUNET_CRYPTO_hash-function to apply per element
+ * @param k the new number of #GNUNET_CRYPTO_hash-function to apply per element
  */
 void
 GNUNET_CONTAINER_bloomfilter_resize (struct GNUNET_CONTAINER_BloomFilter *bf,
@@ -231,22 +256,27 @@ GNUNET_CONTAINER_bloomfilter_resize (struct GNUNET_CONTAINER_BloomFilter *bf,
                                      void *iterator_cls, size_t size,
                                      unsigned int k);
 
+
 /* ****************** metadata ******************* */
 
 /**
+ * @ingroup metadata
  * Meta data to associate with a file, directory or namespace.
  */
 struct GNUNET_CONTAINER_MetaData;
 
 /**
- * Create a fresh MetaData token.
+ * @ingroup metadata
+ * Create a fresh meta data container.
  *
  * @return empty meta-data container
  */
 struct GNUNET_CONTAINER_MetaData *
 GNUNET_CONTAINER_meta_data_create (void);
 
+
 /**
+ * @ingroup metadata
  * Duplicate a MetaData token.
  *
  * @param md what to duplicate
@@ -257,6 +287,7 @@ GNUNET_CONTAINER_meta_data_duplicate (const struct GNUNET_CONTAINER_MetaData
                                       *md);
 
 /**
+ * @ingroup metadata
  * Free meta data.
  *
  * @param md what to free
@@ -264,7 +295,9 @@ GNUNET_CONTAINER_meta_data_duplicate (const struct GNUNET_CONTAINER_MetaData
 void
 GNUNET_CONTAINER_meta_data_destroy (struct GNUNET_CONTAINER_MetaData *md);
 
+
 /**
+ * @ingroup metadata
  * Test if two MDs are equal. We consider them equal if
  * the meta types, formats and content match (we do not
  * include the mime types and plugins names in this
@@ -272,7 +305,7 @@ GNUNET_CONTAINER_meta_data_destroy (struct GNUNET_CONTAINER_MetaData *md);
  *
  * @param md1 first value to check
  * @param md2 other value to check
- * @return GNUNET_YES if they are equal
+ * @return #GNUNET_YES if they are equal
  */
 int
 GNUNET_CONTAINER_meta_data_test_equal (const struct GNUNET_CONTAINER_MetaData
@@ -282,6 +315,7 @@ GNUNET_CONTAINER_meta_data_test_equal (const struct GNUNET_CONTAINER_MetaData
 
 
 /**
+ * @ingroup metadata
  * Extend metadata.
  *
  * @param md metadata to extend
@@ -295,7 +329,7 @@ GNUNET_CONTAINER_meta_data_test_equal (const struct GNUNET_CONTAINER_MetaData
  *        can be NULL (if mime-type is not known)
  * @param data actual meta-data found
  * @param data_size number of bytes in data
- * @return GNUNET_OK on success, GNUNET_SYSERR if this entry already exists
+ * @return #GNUNET_OK on success, #GNUNET_SYSERR if this entry already exists
  *         data_mime_type and plugin_name are not considered for "exists" checks
  */
 int
@@ -308,6 +342,7 @@ GNUNET_CONTAINER_meta_data_insert (struct GNUNET_CONTAINER_MetaData *md,
 
 
 /**
+ * @ingroup metadata
  * Extend metadata.  Merges the meta data from the second argument
  * into the first, discarding duplicate key-value pairs.
  *
@@ -320,6 +355,7 @@ GNUNET_CONTAINER_meta_data_merge (struct GNUNET_CONTAINER_MetaData *md,
 
 
 /**
+ * @ingroup metadata
  * Remove an item.
  *
  * @param md metadata to manipulate
@@ -327,7 +363,7 @@ GNUNET_CONTAINER_meta_data_merge (struct GNUNET_CONTAINER_MetaData *md,
  * @param data specific value to remove, NULL to remove all
  *        entries of the given type
  * @param data_size number of bytes in data
- * @return GNUNET_OK on success, GNUNET_SYSERR if the item does not exist in md
+ * @return #GNUNET_OK on success, #GNUNET_SYSERR if the item does not exist in md
  */
 int
 GNUNET_CONTAINER_meta_data_delete (struct GNUNET_CONTAINER_MetaData *md,
@@ -336,6 +372,7 @@ GNUNET_CONTAINER_meta_data_delete (struct GNUNET_CONTAINER_MetaData *md,
 
 
 /**
+ * @ingroup metadata
  * Remove all items in the container.
  *
  * @param md metadata to manipulate
@@ -345,6 +382,7 @@ GNUNET_CONTAINER_meta_data_clear (struct GNUNET_CONTAINER_MetaData *md);
 
 
 /**
+ * @ingroup metadata
  * Add the current time as the publication date
  * to the meta-data.
  *
@@ -356,11 +394,12 @@ GNUNET_CONTAINER_meta_data_add_publication_date (struct
 
 
 /**
+ * @ingroup metadata
  * Iterate over MD entries.
  *
  * @param md metadata to inspect
  * @param iter function to call on each entry
- * @param iter_cls closure for iterator
+ * @param iter_cls closure for @a iter
  * @return number of entries
  */
 int
@@ -369,6 +408,7 @@ GNUNET_CONTAINER_meta_data_iterate (const struct GNUNET_CONTAINER_MetaData *md,
                                     void *iter_cls);
 
 /**
+ * @ingroup metadata
  * Get the first MD entry of the given type.  Caller
  * is responsible for freeing the return value.
  * Also, only meta data items that are strings (0-terminated)
@@ -384,6 +424,7 @@ GNUNET_CONTAINER_meta_data_get_by_type (const struct GNUNET_CONTAINER_MetaData
 
 
 /**
+ * @ingroup metadata
  * Get the first matching MD entry of the given types. Caller is
  * responsible for freeing the return value.  Also, only meta data
  * items that are strings (0-terminated) are returned by this
@@ -400,6 +441,7 @@ GNUNET_CONTAINER_meta_data_get_first_by_types (const struct
                                                ...);
 
 /**
+ * @ingroup metadata
  * Get a thumbnail from the meta-data (if present).  Only matches meta
  * data with mime type "image" and binary format.
  *
@@ -415,22 +457,26 @@ GNUNET_CONTAINER_meta_data_get_thumbnail (const struct GNUNET_CONTAINER_MetaData
 
 
 /**
+ * @ingroup metadata
  * Options for metadata serialization.
  */
 enum GNUNET_CONTAINER_MetaDataSerializationOptions
 {
   /**
+   * @ingroup metadata
    * Serialize all of the data.
    */
   GNUNET_CONTAINER_META_DATA_SERIALIZE_FULL = 0,
 
   /**
+   * @ingroup metadata
    * If not enough space is available, it is acceptable
    * to only serialize some of the metadata.
    */
   GNUNET_CONTAINER_META_DATA_SERIALIZE_PART = 1,
 
   /**
+   * @ingroup metadata
    * Speed is of the essence, do not allow compression.
    */
   GNUNET_CONTAINER_META_DATA_SERIALIZE_NO_COMPRESS = 2
@@ -438,6 +484,7 @@ enum GNUNET_CONTAINER_MetaDataSerializationOptions
 
 
 /**
+ * @ingroup metadata
  * Serialize meta-data to target.
  *
  * @param md metadata to serialize
@@ -460,6 +507,7 @@ GNUNET_CONTAINER_meta_data_serialize (const struct GNUNET_CONTAINER_MetaData
 
 
 /**
+ * @ingroup metadata
  * Get the size of the full meta-data in serialized form.
  *
  * @param md metadata to inspect
@@ -471,6 +519,7 @@ GNUNET_CONTAINER_meta_data_get_serialized_size (const struct
 
 
 /**
+ * @ingroup metadata
  * Deserialize meta-data.  Initializes md.
  *
  * @param input serialized meta-data.
@@ -485,23 +534,27 @@ GNUNET_CONTAINER_meta_data_deserialize (const char *input, size_t size);
 /* ******************************* HashMap **************************** */
 
 /**
+ * @ingroup hashmap
  * Opaque handle for a HashMap.
  */
 struct GNUNET_CONTAINER_MultiHashMap;
 
 /**
+ * @ingroup hashmap
  * Opaque handle to an iterator over
  * a multihashmap.
  */
 struct GNUNET_CONTAINER_MultiHashMapIterator;
 
 /**
+ * @ingroup hashmap
  * Options for storing values in the HashMap.
  */
 enum GNUNET_CONTAINER_MultiHashMapOption
 {
 
   /**
+   * @ingroup hashmap
    * If a value with the given key exists, replace it.  Note that the
    * old value would NOT be freed by replace (the application has to
    * make sure that this happens if required).
@@ -509,35 +562,41 @@ enum GNUNET_CONTAINER_MultiHashMapOption
   GNUNET_CONTAINER_MULTIHASHMAPOPTION_REPLACE,
 
   /**
+   * @ingroup hashmap
    * Allow multiple values with the same key.
    */
   GNUNET_CONTAINER_MULTIHASHMAPOPTION_MULTIPLE,
 
   /**
+   * @ingroup hashmap
    * There must only be one value per key; storing a value should fail
    * if a value under the same key already exists.
    */
   GNUNET_CONTAINER_MULTIHASHMAPOPTION_UNIQUE_ONLY,
 
   /**
-   * There must only be one value per key, but don't bother checking
-   * if a value already exists (faster than UNIQUE_ONLY; implemented
-   * just like MULTIPLE but this option documents better what is
-   * intended if UNIQUE is what is desired).
+   * @ingroup hashmap There must only be one value per key, but don't
+   * bother checking if a value already exists (faster than
+   * #GNUNET_CONTAINER_MULTIHASHMAPOPTION_UNIQUE_ONLY; implemented
+   * just like #GNUNET_CONTAINER_MULTIHASHMAPOPTION_MULTIPLE but this
+   * option documents better what is intended if
+   * #GNUNET_CONTAINER_MULTIHASHMAPOPTION_UNIQUE_ONLY is what is
+   * desired).
    */
   GNUNET_CONTAINER_MULTIHASHMAPOPTION_UNIQUE_FAST
 };
 
 
 /**
+ * @ingroup hashmap
  * Iterator over hash map entries.
  *
  * @param cls closure
  * @param key current key code
  * @param value value in the hash map
- * @return GNUNET_YES if we should continue to
+ * @return #GNUNET_YES if we should continue to
  *         iterate,
- *         GNUNET_NO if not.
+ *         #GNUNET_NO if not.
  */
 typedef int (*GNUNET_CONTAINER_HashMapIterator) (void *cls,
                                                  const struct GNUNET_HashCode *key,
@@ -545,11 +604,12 @@ typedef int (*GNUNET_CONTAINER_HashMapIterator) (void *cls,
 
 
 /**
+ * @ingroup hashmap
  * Create a multi hash map.
  *
  * @param len initial size (map will grow as needed)
- * @param do_not_copy_keys GNUNET_NO is always safe and should be used by default;
- *                         GNUNET_YES means that on 'put', the 'key' does not have
+ * @param do_not_copy_keys #GNUNET_NO is always safe and should be used by default;
+ *                         #GNUNET_YES means that on 'put', the 'key' does not have
  *                         to be copied as the destination of the pointer is 
  *                         guaranteed to be life as long as the value is stored in
  *                         the hashmap.  This can significantly reduce memory 
@@ -565,6 +625,7 @@ GNUNET_CONTAINER_multihashmap_create (unsigned int len,
 
 
 /**
+ * @ingroup hashmap
  * Destroy a hash map.  Will not free any values
  * stored in the hash map!
  *
@@ -576,6 +637,7 @@ GNUNET_CONTAINER_multihashmap_destroy (struct GNUNET_CONTAINER_MultiHashMap
 
 
 /**
+ * @ingroup hashmap
  * Given a key find a value in the map matching the key.
  *
  * @param map the map
@@ -591,6 +653,7 @@ GNUNET_CONTAINER_multihashmap_get (const struct GNUNET_CONTAINER_MultiHashMap
 
 
 /**
+ * @ingroup hashmap
  * Remove the given key-value pair from the map.  Note that if the
  * key-value pair is in the map multiple times, only one of the pairs
  * will be removed.
@@ -598,7 +661,7 @@ GNUNET_CONTAINER_multihashmap_get (const struct GNUNET_CONTAINER_MultiHashMap
  * @param map the map
  * @param key key of the key-value pair
  * @param value value of the key-value pair
- * @return GNUNET_YES on success, GNUNET_NO if the key-value pair
+ * @return #GNUNET_YES on success, #GNUNET_NO if the key-value pair
  *  is not in the map
  */
 int
@@ -607,6 +670,7 @@ GNUNET_CONTAINER_multihashmap_remove (struct GNUNET_CONTAINER_MultiHashMap *map,
                                       const void *value);
 
 /**
+ * @ingroup hashmap
  * Remove all entries for the given key from the map.
  * Note that the values would not be "freed".
  *
@@ -620,13 +684,14 @@ GNUNET_CONTAINER_multihashmap_remove_all (struct GNUNET_CONTAINER_MultiHashMap
 
 
 /**
+ * @ingroup hashmap
  * Check if the map contains any value under the given
  * key (including values that are NULL).
  *
  * @param map the map
  * @param key the key to test if a value exists for it
- * @return GNUNET_YES if such a value exists,
- *         GNUNET_NO if not
+ * @return #GNUNET_YES if such a value exists,
+ *         #GNUNET_NO if not
  */
 int
 GNUNET_CONTAINER_multihashmap_contains (const struct
@@ -635,14 +700,15 @@ GNUNET_CONTAINER_multihashmap_contains (const struct
 
 
 /**
+ * @ingroup hashmap
  * Check if the map contains the given value under the given
  * key.
  *
  * @param map the map
  * @param key the key to test if a value exists for it
  * @param value value to test for
- * @return GNUNET_YES if such a value exists,
- *         GNUNET_NO if not
+ * @return #GNUNET_YES if such a value exists,
+ *         #GNUNET_NO if not
  */
 int
 GNUNET_CONTAINER_multihashmap_contains_value (const struct
@@ -652,15 +718,16 @@ GNUNET_CONTAINER_multihashmap_contains_value (const struct
 
 
 /**
+ * @ingroup hashmap
  * Store a key-value pair in the map.
  *
  * @param map the map
  * @param key key to use
  * @param value value to use
  * @param opt options for put
- * @return GNUNET_OK on success,
- *         GNUNET_NO if a value was replaced (with REPLACE)
- *         GNUNET_SYSERR if UNIQUE_ONLY was the option and the
+ * @return #GNUNET_OK on success,
+ *         #GNUNET_NO if a value was replaced (with REPLACE)
+ *         #GNUNET_SYSERR if UNIQUE_ONLY was the option and the
  *                       value already exists
  */
 int
@@ -670,6 +737,7 @@ GNUNET_CONTAINER_multihashmap_put (struct GNUNET_CONTAINER_MultiHashMap *map,
                                    opt);
 
 /**
+ * @ingroup hashmap
  * Get the number of key-value pairs in the map.
  *
  * @param map the map
@@ -681,13 +749,14 @@ GNUNET_CONTAINER_multihashmap_size (const struct GNUNET_CONTAINER_MultiHashMap
 
 
 /**
+ * @ingroup hashmap
  * Iterate over all entries in the map.
  *
  * @param map the map
  * @param it function to call on each entry
- * @param it_cls extra argument to it
+ * @param it_cls extra argument to @a it
  * @return the number of key value pairs processed,
- *         GNUNET_SYSERR if it aborted iteration
+ *         #GNUNET_SYSERR if it aborted iteration
  */
 int
 GNUNET_CONTAINER_multihashmap_iterate (const struct
@@ -697,6 +766,7 @@ GNUNET_CONTAINER_multihashmap_iterate (const struct
 
 
 /**
+ * @ingroup hashmap
  * Create an iterator for a multihashmap.
  * The iterator can be used to retrieve all the elements in the multihashmap
  * one by one, without having to handle all elements at once (in contrast to
@@ -706,25 +776,26 @@ GNUNET_CONTAINER_multihashmap_iterate (const struct
  * result in skipped or repeated elements.
  *
  * @param map the map to create an iterator for
- * @return an iterator over the given multihashmap 'map'
+ * @return an iterator over the given multihashmap @a map
  */
 struct GNUNET_CONTAINER_MultiHashMapIterator *
 GNUNET_CONTAINER_multihashmap_iterator_create (const struct GNUNET_CONTAINER_MultiHashMap *map);
 
 
 /**
- * Retrieve the next element from the hash map at the iterator's position.
- * If there are no elements left, GNUNET_NO is returned, and 'key' and 'value'
- * are not modified.
- * This operation is only allowed if no elements have been removed from the
- * multihashmap since the creation of 'iter', and the map has not been destroyed.
+ * @ingroup hashmap 
+ * Retrieve the next element from the hash map at the iterator's
+ * position.  If there are no elements left, #GNUNET_NO is returned,
+ * and @a key and @a value are not modified.  This operation is only
+ * allowed if no elements have been removed from the multihashmap
+ * since the creation of @a iter, and the map has not been destroyed.
  * Adding elements may result in repeating or skipping elements.
  *
  * @param iter the iterator to get the next element from
  * @param key pointer to store the key in, can be NULL
  * @param value pointer to store the value in, can be NULL
- * @return GNUNET_YES we returned an element,
- *         GNUNET_NO if we are out of elements
+ * @return #GNUNET_YES we returned an element,
+ *         #GNUNET_NO if we are out of elements
  */
 int
 GNUNET_CONTAINER_multihashmap_iterator_next (struct GNUNET_CONTAINER_MultiHashMapIterator *iter,
@@ -732,6 +803,7 @@ GNUNET_CONTAINER_multihashmap_iterator_next (struct GNUNET_CONTAINER_MultiHashMa
 
 
 /**
+ * @ingroup hashmap 
  * Destroy a multihashmap iterator.
  *
  * @param iter the iterator to destroy
@@ -741,14 +813,15 @@ GNUNET_CONTAINER_multihashmap_iterator_destroy (struct GNUNET_CONTAINER_MultiHas
 
 
 /**
+ * @ingroup hashmap 
  * Iterate over all entries in the map that match a particular key.
  *
  * @param map the map
  * @param key key that the entries must correspond to
  * @param it function to call on each entry
- * @param it_cls extra argument to it
+ * @param it_cls extra argument to @a it
  * @return the number of key value pairs processed,
- *         GNUNET_SYSERR if it aborted iteration
+ *         #GNUNET_SYSERR if it aborted iteration
  */
 int
 GNUNET_CONTAINER_multihashmap_get_multiple (const struct
@@ -760,20 +833,22 @@ GNUNET_CONTAINER_multihashmap_get_multiple (const struct
 /* Version of multihashmap with 32 bit keys */
 
 /**
+ * @ingroup hashmap 
  * Opaque handle for the 32-bit key HashMap.
  */
 struct GNUNET_CONTAINER_MultiHashMap32;
 
 
 /**
+ * @ingroup hashmap 
  * Iterator over hash map entries.
  *
  * @param cls closure
  * @param key current key code
  * @param value value in the hash map
- * @return GNUNET_YES if we should continue to
+ * @return #GNUNET_YES if we should continue to
  *         iterate,
- *         GNUNET_NO if not.
+ *         #GNUNET_NO if not.
  */
 typedef int (*GNUNET_CONTAINER_HashMapIterator32) (void *cls,
                                                    uint32_t key,
@@ -781,6 +856,7 @@ typedef int (*GNUNET_CONTAINER_HashMapIterator32) (void *cls,
 
 
 /**
+ * @ingroup hashmap 
  * Create a 32-bit key multi hash map.
  *
  * @param len initial size (map will grow as needed)
@@ -791,6 +867,7 @@ GNUNET_CONTAINER_multihashmap32_create (unsigned int len);
 
 
 /**
+ * @ingroup hashmap 
  * Destroy a 32-bit key hash map.  Will not free any values
  * stored in the hash map!
  *
@@ -802,6 +879,7 @@ GNUNET_CONTAINER_multihashmap32_destroy (struct GNUNET_CONTAINER_MultiHashMap32
 
 
 /**
+ * @ingroup hashmap 
  * Get the number of key-value pairs in the map.
  *
  * @param map the map
@@ -813,6 +891,7 @@ GNUNET_CONTAINER_multihashmap32_size (const struct
 
 
 /**
+ * @ingroup hashmap 
  * Given a key find a value in the map matching the key.
  *
  * @param map the map
@@ -829,13 +908,14 @@ GNUNET_CONTAINER_multihashmap32_get (const struct
 
 
 /**
+ * @ingroup hashmap 
  * Iterate over all entries in the map.
  *
  * @param map the map
  * @param it function to call on each entry
- * @param it_cls extra argument to it
+ * @param it_cls extra argument to @a it
  * @return the number of key value pairs processed,
- *         GNUNET_SYSERR if it aborted iteration
+ *         #GNUNET_SYSERR if it aborted iteration
  */
 int
 GNUNET_CONTAINER_multihashmap32_iterate (const struct
@@ -845,6 +925,7 @@ GNUNET_CONTAINER_multihashmap32_iterate (const struct
 
 
 /**
+ * @ingroup hashmap 
  * Remove the given key-value pair from the map.  Note that if the
  * key-value pair is in the map multiple times, only one of the pairs
  * will be removed.
@@ -852,7 +933,7 @@ GNUNET_CONTAINER_multihashmap32_iterate (const struct
  * @param map the map
  * @param key key of the key-value pair
  * @param value value of the key-value pair
- * @return GNUNET_YES on success, GNUNET_NO if the key-value pair
+ * @return #GNUNET_YES on success, #GNUNET_NO if the key-value pair
  *  is not in the map
  */
 int
@@ -863,6 +944,7 @@ GNUNET_CONTAINER_multihashmap32_remove (struct GNUNET_CONTAINER_MultiHashMap32
 
 
 /**
+ * @ingroup hashmap 
  * Remove all entries for the given key from the map.
  * Note that the values would not be "freed".
  *
@@ -878,13 +960,14 @@ GNUNET_CONTAINER_multihashmap32_remove_all (struct
 
 
 /**
+ * @ingroup hashmap 
  * Check if the map contains any value under the given
  * key (including values that are NULL).
  *
  * @param map the map
  * @param key the key to test if a value exists for it
- * @return GNUNET_YES if such a value exists,
- *         GNUNET_NO if not
+ * @return #GNUNET_YES if such a value exists,
+ *         #GNUNET_NO if not
  */
 int
 GNUNET_CONTAINER_multihashmap32_contains (const struct
@@ -893,14 +976,15 @@ GNUNET_CONTAINER_multihashmap32_contains (const struct
 
 
 /**
+ * @ingroup hashmap 
  * Check if the map contains the given value under the given
  * key.
  *
  * @param map the map
  * @param key the key to test if a value exists for it
  * @param value value to test for
- * @return GNUNET_YES if such a value exists,
- *         GNUNET_NO if not
+ * @return #GNUNET_YES if such a value exists,
+ *         #GNUNET_NO if not
  */
 int
 GNUNET_CONTAINER_multihashmap32_contains_value (const struct
@@ -911,15 +995,16 @@ GNUNET_CONTAINER_multihashmap32_contains_value (const struct
 
 
 /**
+ * @ingroup hashmap 
  * Store a key-value pair in the map.
  *
  * @param map the map
  * @param key key to use
  * @param value value to use
  * @param opt options for put
- * @return GNUNET_OK on success,
- *         GNUNET_NO if a value was replaced (with REPLACE)
- *         GNUNET_SYSERR if UNIQUE_ONLY was the option and the
+ * @return #GNUNET_OK on success,
+ *         #GNUNET_NO if a value was replaced (with REPLACE)
+ *         #GNUNET_SYSERR if #GNUNET_CONTAINER_MULTIHASHMAPOPTION_UNIQUE_ONLY was the option and the
  *                       value already exists
  */
 int
@@ -930,14 +1015,15 @@ GNUNET_CONTAINER_multihashmap32_put (struct GNUNET_CONTAINER_MultiHashMap32
 
 
 /**
+ * @ingroup hashmap 
  * Iterate over all entries in the map that match a particular key.
  *
  * @param map the map
  * @param key key that the entries must correspond to
  * @param it function to call on each entry
- * @param it_cls extra argument to it
+ * @param it_cls extra argument to @a it
  * @return the number of key value pairs processed,
- *         GNUNET_SYSERR if it aborted iteration
+ *         #GNUNET_SYSERR if it aborted iteration
  */
 int
 GNUNET_CONTAINER_multihashmap32_get_multiple (const struct
@@ -953,6 +1039,7 @@ GNUNET_CONTAINER_multihashmap32_get_multiple (const struct
 /* To avoid mistakes: head->prev == tail->next == NULL     */
 
 /**
+ * @ingroup dll 
  * Insert an element at the head of a DLL. Assumes that head, tail and
  * element are structs with prev and next fields.
  *
@@ -973,6 +1060,7 @@ GNUNET_CONTAINER_multihashmap32_get_multiple (const struct
 
 
 /**
+ * @ingroup dll 
  * Insert an element at the tail of a DLL. Assumes that head, tail and
  * element are structs with prev and next fields.
  *
@@ -993,6 +1081,7 @@ GNUNET_CONTAINER_multihashmap32_get_multiple (const struct
 
 
 /**
+ * @ingroup dll 
  * Insert an element into a DLL after the given other element.  Insert
  * at the head if the other element is NULL.
  *
@@ -1022,6 +1111,7 @@ GNUNET_CONTAINER_multihashmap32_get_multiple (const struct
 
 
 /**
+ * @ingroup dll 
  * Insert an element into a DLL before the given other element.  Insert
  * at the tail if the other element is NULL.
  *
@@ -1051,6 +1141,7 @@ GNUNET_CONTAINER_multihashmap32_get_multiple (const struct
 
 
 /**
+ * @ingroup dll 
  * Remove an element from a DLL. Assumes that head, tail and
  * element point to structs with prev and next fields.
  *
@@ -1082,6 +1173,7 @@ GNUNET_CONTAINER_multihashmap32_get_multiple (const struct
    in multiple lists at the same time *********************** */
 
 /**
+ * @ingroup dll 
  * Insert an element at the head of a MDLL. Assumes that head, tail and
  * element are structs with prev and next fields.
  *
@@ -1103,6 +1195,7 @@ GNUNET_CONTAINER_multihashmap32_get_multiple (const struct
 
 
 /**
+ * @ingroup dll 
  * Insert an element at the tail of a MDLL. Assumes that head, tail and
  * element are structs with prev and next fields.
  *
@@ -1124,6 +1217,7 @@ GNUNET_CONTAINER_multihashmap32_get_multiple (const struct
 
 
 /**
+ * @ingroup dll 
  * Insert an element into a MDLL after the given other element.  Insert
  * at the head if the other element is NULL.
  *
@@ -1154,6 +1248,7 @@ GNUNET_CONTAINER_multihashmap32_get_multiple (const struct
 
 
 /**
+ * @ingroup dll 
  * Insert an element into a MDLL before the given other element.  Insert
  * at the tail if the other element is NULL.
  *
@@ -1184,6 +1279,7 @@ GNUNET_CONTAINER_multihashmap32_get_multiple (const struct
 
 
 /**
+ * @ingroup dll 
  * Remove an element from a MDLL. Assumes
  * that head, tail and element are structs
  * with prev and next fields.
@@ -1213,23 +1309,26 @@ GNUNET_CONTAINER_multihashmap32_get_multiple (const struct
 
 
 /**
+ * @ingroup heap
  * Cost by which elements in a heap can be ordered.
  */
 typedef uint64_t GNUNET_CONTAINER_HeapCostType;
 
 
-/*
- * Heap type, either max or min.  Hopefully makes the
- * implementation more useful.
+/**
+ * @ingroup heap
+ * Heap type, either max or min.
  */
 enum GNUNET_CONTAINER_HeapOrder
 {
   /**
+   * @ingroup heap
    * Heap with the maximum cost at the root.
    */
   GNUNET_CONTAINER_HEAP_ORDER_MAX,
 
   /**
+   * @ingroup heap
    * Heap with the minimum cost at the root.
    */
   GNUNET_CONTAINER_HEAP_ORDER_MIN
@@ -1237,19 +1336,21 @@ enum GNUNET_CONTAINER_HeapOrder
 
 
 /**
+ * @ingroup heap
  * Handle to a Heap.
  */
 struct GNUNET_CONTAINER_Heap;
 
 
-
 /**
+ * @ingroup heap
  * Handle to a node in a heap.
  */
 struct GNUNET_CONTAINER_HeapNode;
 
 
 /**
+ * @ingroup heap
  * Create a new heap.
  *
  * @param order how should the heap be sorted?
@@ -1260,6 +1361,7 @@ GNUNET_CONTAINER_heap_create (enum GNUNET_CONTAINER_HeapOrder order);
 
 
 /**
+ * @ingroup heap
  * Destroys the heap.  Only call on a heap that
  * is already empty.
  *
@@ -1270,6 +1372,7 @@ GNUNET_CONTAINER_heap_destroy (struct GNUNET_CONTAINER_Heap *heap);
 
 
 /**
+ * @ingroup heap
  * Get element stored at root of heap.
  *
  * @param heap heap to inspect
@@ -1280,6 +1383,7 @@ GNUNET_CONTAINER_heap_peek (const struct GNUNET_CONTAINER_Heap *heap);
 
 
 /**
+ * @ingroup heap
  * Get the current size of the heap
  *
  * @param heap the heap to get the size of
@@ -1290,6 +1394,7 @@ GNUNET_CONTAINER_heap_get_size (const struct GNUNET_CONTAINER_Heap *heap);
 
 
 /**
+ * @ingroup heap
  * Get the current cost of the node
  *
  * @param node the node to get the cost of
@@ -1300,14 +1405,15 @@ GNUNET_CONTAINER_heap_node_get_cost (const struct GNUNET_CONTAINER_HeapNode
                                      *node);
 
 /**
+ * @ingroup heap
  * Iterator for heap
  *
  * @param cls closure
  * @param node internal node of the heap
  * @param element value stored at the node
  * @param cost cost associated with the node
- * @return GNUNET_YES if we should continue to iterate,
- *         GNUNET_NO if not.
+ * @return #GNUNET_YES if we should continue to iterate,
+ *         #GNUNET_NO if not.
  */
 typedef int (*GNUNET_CONTAINER_HeapIterator) (void *cls,
                                               struct GNUNET_CONTAINER_HeapNode *
@@ -1317,11 +1423,12 @@ typedef int (*GNUNET_CONTAINER_HeapIterator) (void *cls,
 
 
 /**
+ * @ingroup heap
  * Iterate over all entries in the heap.
  *
  * @param heap the heap
  * @param iterator function to call on each entry
- * @param iterator_cls closure for iterator
+ * @param iterator_cls closure for @a iterator
  */
 void
 GNUNET_CONTAINER_heap_iterate (const struct GNUNET_CONTAINER_Heap *heap,
@@ -1329,6 +1436,7 @@ GNUNET_CONTAINER_heap_iterate (const struct GNUNET_CONTAINER_Heap *heap,
                                void *iterator_cls);
 
 /**
+ * @ingroup heap
  * Perform a random walk of the tree.  The walk is biased
  * towards elements closer to the root of the tree (since
  * each walk starts at the root and ends at a random leaf).
@@ -1344,6 +1452,7 @@ GNUNET_CONTAINER_heap_walk_get_next (struct GNUNET_CONTAINER_Heap *heap);
 
 
 /**
+ * @ingroup heap
  * Inserts a new element into the heap.
  *
  * @param heap heap to modify
@@ -1357,6 +1466,7 @@ GNUNET_CONTAINER_heap_insert (struct GNUNET_CONTAINER_Heap *heap, void *element,
 
 
 /**
+ * @ingroup heap
  * Remove root of the heap.
  *
  * @param heap heap to modify
@@ -1367,6 +1477,7 @@ GNUNET_CONTAINER_heap_remove_root (struct GNUNET_CONTAINER_Heap *heap);
 
 
 /**
+ * @ingroup heap
  * Removes a node from the heap.
  *
  * @param node node to remove
@@ -1377,6 +1488,7 @@ GNUNET_CONTAINER_heap_remove_node (struct GNUNET_CONTAINER_HeapNode *node);
 
 
 /**
+ * @ingroup heap
  * Updates the cost of any node in the tree
  *
  * @param heap heap to modify