map: convert comments to doxygen format

3 files changed, 66 insertions, 22 deletions

diff --git a/doc/index.rst b/doc/index.rst
index b9ad6ed..c7f8b10 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -7,3 +7,4 @@ Vis Editor API Documenation
    text
    buffer
    array
+   map
diff --git a/doc/map.rst b/doc/map.rst
new file mode 100644
index 0000000..aba5227
--- /dev/null
+++ b/doc/map.rst
@@ -0,0 +1,4 @@
+Map
+===
+
+.. doxygenfile:: map.h
diff --git a/map.h b/map.h
index d4ea992..bfda118 100644
--- a/map.h
+++ b/map.h
@@ -3,44 +3,83 @@
 
 #include <stdbool.h>
 
+/**
+ * @file
+ * Crit-bit tree based map which supports unique prefix queries and
+ * ordered iteration.
+ */
+
+/** Opaque map type. */
 typedef struct Map Map;
 
-/* Allocate a new map. */
+/** Allocate a new map. */
 Map *map_new(void);
-/* Retrieves a value, or NULL if it isn't in the map */
+/** Lookup a value, returns ``NULL`` if not found. */
 void *map_get(const Map*, const char *key);
-/* Get first element of the map, or NULL if empty */
+/**
+ * Get first element of the map, or ``NULL`` if empty.
+ * @param key Updated with the key of the first element.
+ */
 void *map_first(const Map*, const char **key);
-/* Returns the corresponding value if the given prefix is unique.
- * Otherwise NULL, if no such prefix exists then errno is set to ENOENT. */
+/**
+ * Lookup element by unique prefix match.
+ * @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``.
+ */
 void *map_closest(const Map*, const char *prefix);
-/* check whether the map contains the given prefix, i.e. whether it can
- * be extended to match a key of an element stored in the map. */
+/**
+ * Check whether the map contains the given prefix.
+ * whether it can be extended to match a key of a map element.
+ */
 bool map_contains(const Map*, const char *prefix);
-/* Test whether the given prefix can be extended to exactly one map element
- * i.e. true iff the prefix map contains exactly one element. */
+/**
+ * Check whether the given prefix can be extended to exactly one map element.
+ * True iff the prefix map contains exactly one element.
+ */
 bool map_leaf(const Map*, const char *prefix);
-/* Place a member in the map. This returns false if we run out of memory
- * (errno = ENOMEM), or if that key already appears in the map (errno = EEXIST). */
+/**
+ * Store a key value pair in the map.
+ * @return False if we run out of memory (``errno = ENOMEM``), or if the key
+ *         already appears in the map (``errno = EEXIST``).
+ */
 bool map_put(Map*, const char *key, const void *value);
-/* Remove a member from the map. Returns the removed entry or NULL
- * if there was no entry found using the given key*/
+/**
+ * Remove a map element.
+ * @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' */
+/** Copy all entries from ``src`` into ``dest``, overwrites existing entries in ``dest``. */
 bool map_copy(Map *dest, Map *src);
-/* Ordered iteration over a map, call handle for every entry. If handle
- * returns false, the iteration will stop. */
+/**
+ * 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 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);
-/* Return a submap matching a prefix. This returns a pointer into the
- * original map, so don't alter the map while using the return value. */
+/**
+ * Get a sub map matching a prefix.
+ * @rst
+ * .. warning:: This returns a pointer into the original map.
+ *              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 i.e. contains no elements */
+/** Test whether the map is empty (contains no elements). */
 bool map_empty(const Map*);
-/* Remove every member from the map. The map will be empty after this. */
+/** Empty the map. */
 void map_clear(Map*);
-/* Release all memory associated with this map */
+/** Release all memory associated with this map. */
 void map_free(Map*);
-/* Call free(3) for every pointer stored in the map, then free the map itself */
+/**
+ * Call `free(3)` for every map element, then free the map itself.
+ * @rst
+ * .. warning:: Assumes map elements to be pointers.
+ * @endrst
+ */
 void map_free_full(Map*);
 
 #endif