From f21d256f3f3fae59dff8c0ae30368c408bbd2af1 Mon Sep 17 00:00:00 2001
From: dg <dg>
Date: Sun, 8 Jan 2023 11:27:46 +0000
Subject: [PATCH] Update documentation.

---
 modules/src/data/pmap.h | 26 ++++++++++++++++++++++++++
 modules/src/data/smap.h | 29 ++++++++++++++++++++---------
 2 files changed, 46 insertions(+), 9 deletions(-)

diff --git a/modules/src/data/pmap.h b/modules/src/data/pmap.h
index a7980a3a3..dd17f1c24 100644
--- a/modules/src/data/pmap.h
+++ b/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
diff --git a/modules/src/data/smap.h b/modules/src/data/smap.h
index eef2488c1..8e82639f7 100644
--- a/modules/src/data/smap.h
+++ b/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
- *  handle in `mapp`.
+/** Initializes a string map. Optional; a zero-initialised map
+ * 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
- *  value `value` associated with the existing `key`.
+
+/** Adds a new item with name `key` in the string map if it does not already
+ * 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