doc: fix Doxygen comments for map.h

1 files changed, 53 insertions, 23 deletions

diff --git a/map.h b/map.h
index 54dd22b..e733bd3 100644
--- a/map.h
+++ b/map.h
@@ -14,67 +14,97 @@ typedef struct Map Map;
 
 /** Allocate a new map. */
 Map *map_new(void);
-/** Lookup a value, returns ``NULL`` if not found. */
-void *map_get(const Map*, const char *key);
+/**
+ * Lookup a value, returns ``NULL`` if not found.
+ * @param map The map to search within.
+ * @param key The key to look up.
+ */
+void *map_get(const Map *map, const char *key);
 /**
  * Get first element of the map, or ``NULL`` if empty.
+ * @param map The map to query.
  * @param key Updated with the key of the first element.
  */
-void *map_first(const Map*, const char **key);
+void *map_first(const Map *map, const char **key);
 /**
  * Lookup element by unique prefix match.
+ * @param map The map to search within.
  * @param prefix The prefix to search for.
  * @return The corresponding value, if the given prefix is unique.
- *         Otherwise ``NULL``. If no such prefix exists, then ``errno``
- *         is set to ``ENOENT``.
+ * Otherwise ``NULL``. If no such prefix exists, then ``errno``
+ * is set to ``ENOENT``.
  */
-void *map_closest(const Map*, const char *prefix);
+void *map_closest(const Map *map, const char *prefix);
 /**
- * Check whether the map contains the given prefix.
+ * Check whether the map contains the given prefix, or
  * whether it can be extended to match a key of a map element.
+ * @param map The map to check.
+ * @param prefix The prefix to search for.
  */
-bool map_contains(const Map*, const char *prefix);
+bool map_contains(const Map *map, const char *prefix);
 /**
  * Store a key value pair in the map.
+ * @param map The map to store the key-value pair in.
+ * @param key The key to store.
+ * @param value The value associated with the key.
  * @return False if we run out of memory (``errno = ENOMEM``), or if the key
- *         already appears in the map (``errno = EEXIST``).
+ * already appears in the map (``errno = EEXIST``).
  */
-bool map_put(Map*, const char *key, const void *value);
+bool map_put(Map *map, const char *key, const void *value);
 /**
  * Remove a map element.
+ * @param map The map to remove the element from.
+ * @param key The key of the element to remove.
  * @return The removed entry or ``NULL`` if no such element exists.
  */
-void *map_delete(Map*, const char *key);
-/** Copy all entries from ``src`` into ``dest``, overwrites existing entries in ``dest``. */
+void *map_delete(Map *map, const char *key);
+/**
+ * Copy all entries from ``src`` into ``dest``, overwrites existing entries in ``dest``.
+ * @param dest The destination map.
+ * @param src The source map.
+ */
 bool map_copy(Map *dest, Map *src);
 /**
  * Ordered iteration over a map.
  * Invokes the passed callback for every map entry.
  * If ``handle`` returns false, the iteration will stop.
- * @param handle A function invoked for ever map element.
+ * @param map The map to iterate over.
+ * @param handle A function invoked for every map element.
  * @param data A context pointer, passed as last argument to ``handle``.
  */
-void map_iterate(const Map*, bool (*handle)(const char *key, void *value, void *data), const void *data);
+void map_iterate(const Map *map, bool (*handle)(const char *key, void *value, void *data), const void *data);
 /**
  * Get a sub map matching a prefix.
+ * @param map The map to get the sub-map from.
+ * @param prefix The prefix to match.
  * @rst
  * .. warning:: This returns a pointer into the original map.
- *              Do not alter the map while using the return value.
+ * Do not alter the map while using the return value.
  * @endrst
  */
-const Map *map_prefix(const Map*, const char *prefix);
-/** Test whether the map is empty (contains no elements). */
-bool map_empty(const Map*);
-/** Empty the map. */
-void map_clear(Map*);
-/** Release all memory associated with this map. */
-void map_free(Map*);
+const Map *map_prefix(const Map *map, const char *prefix);
+/**
+ * Test whether the map is empty (contains no elements).
+ * @param map The map to check.
+ */
+bool map_empty(const Map *map);
+/**
+ * Empty the map.
+ * @param map The map to clear.
+ */
+void map_clear(Map *map);
+/**
+ * Release all memory associated with this map.
+ * @param map The map to free.
+ */
+void map_free(Map *map);
 /**
  * Call `free(3)` for every map element, then free the map itself.
+ * @param map The map to free its elements and itself.
  * @rst
  * .. warning:: Assumes map elements to be pointers.
  * @endrst
  */
-void map_free_full(Map*);
+void map_free_full(Map *map);
 
 #endif