Update documentation.

modules/src/data/pmap.h

@@ -1,6 +1,9 @@
 #ifndef PMAP_H
 #define PMAP_H
 
+/* A bidirectional multimap, storing (left, right) tuples.
+ */
+
 struct pmap_node
 {
 	void* left;
@@ -23,10 +26,33 @@ struct pmap
 		int max; \
 	}
 
+/** Adds a new relation `(left -> right)` to the map
+ * if `left` is not present. Otherwise replaces the
+ * `right` associated with the first `left`.
+ *
+ * Use this in normal map mode.
+ */
 extern void pmap_put(void* map, void* left, void* right);
+
+/** Adds a new relation to the map if that relation does
+ * not already exist.
+ *
+ * Use this in multimap mode.
+ */
 extern void pmap_add(void* map, void* left, void* right);
+
+/** Removes a relation from the map.
+ *
+ * Use this in multimap mode.
+ */
 extern void pmap_remove(void* map, void* left, void* right);
+
+/** Given a `left`, find the first matching `right`.
+ */
 extern void* pmap_findleft(void* map, void* left);
+
+/** Given a `right`, find the first matching `left`.
+ */
 extern void* pmap_findright(void* map, void* right);
 
 #endif

modules/src/data/smap.h

@@ -6,6 +6,8 @@
 #ifndef SMAP_H
 #define SMAP_H
 
+/* A string multimap (each key can have multiple values). */
+
 struct smap_node
 {
 	const char* left;
@@ -28,24 +30,33 @@ struct smap
 		int max; \
 	}
 
-/** Initializes a string map and returns the initialized
+/** Initializes a string map. Optional; a zero-initialised map
- *  handle in `mapp`.
+ * structure is a valid empty map.
  */
 extern void smap_init(void *mapp);
-/** Adds a new item with name `key` in the string map if
+
- *  it does not already exist, otherwise replaces the
+/** Adds a new item with name `key` in the string map if it does not already
- *  value `value` associated with the existing `key`.
+ * exist. Otherwise replaces the value `value` associated with the existing
+ * `key`.
+ *
+ * Use this for normal map mode.
  */
 extern void smap_put(void *mapp, const char* key, void* value);
-/** Adds a new item in a string map only if `key` does
+
- *  not already exist in the string map.
+/** Adds a new item with name `key` and value `value`. If that relation already
+ * exists, nothing happens.
+ *
+ * Use this for multimap mode.
  */
 extern void smap_add(void *mapp, const char* key, void* value);
-/** Returns the value associated with the specified `key`, returns
+
- *  NULL if `key` is not present in the string map.
+/** Returns the first value associated with the specified `key`. Returns NULL
+ * if `key` is not present in the string map.
  *
+ * Use this in normal map mode.
  */
 extern void* smap_get(void* mapp, const char* key);
+
 /** Frees the data structure associated with the string map.
  *  Also frees the memory associated with the key if
  *  `free_key` is non-zero, and free the memory associated