# HG changeset patch
# User Mike Becker <universe@uap-core.de>
# Date 1688742675 -7200
# Node ID a3b5f27ad956b5a129233e8f9d96114164f530e1
# Parent  9c097dabba2c2f00026f16b13004ca993a2758e1
add map documentation

diff -r 9c097dabba2c -r a3b5f27ad956 docs/src/features.md
--- a/docs/src/features.md	Mon Jul 03 18:37:19 2023 +0200
+++ b/docs/src/features.md	Fri Jul 07 17:11:15 2023 +0200
@@ -307,10 +307,38 @@
 
 *Header file:* [map.h](api/map_8h.html)
 
+Similar to the list interface, the map interface provides a common API for implementing maps.
+There are some minor subtle differences, though.
+
+First, the `remove` method is not always a destructive removal.
+Instead, the last argument is a Boolean that indicates whether the element shall be destroyed or returned.
+```c
+void *(*remove)(CxMap *map, CxHashKey key, bool destroy);
+```
+When you implement this method, you are either supposed to invoke the destructors and return `NULL`,
+or just remove the element from the map and return it.
+
+Secondly, the iterator method is a bit more complete. The signature is as follows:
+```c
+CxIterator (*iterator)(CxMap const *map, enum cx_map_iterator_type type);
+```
+There are three map iterator types: for values, for keys, for pairs.
+Depending on the iterator type requested, you need to create an iterator with the correct methods that
+return the requested thing.
+There are no automatic checks to enforce this - it's completely up to you.
+If you need inspiration on how to do that, check the hash map implementation that comes with UCX.
+
 ### Hash Map
 
 *Header file:* [hash_map.h](api/hash__map_8h.html)
 
+UCX provides a basic hash map implementation with a configurable amount of buckets.
+If you do not specify the number of buckets, a default of 16 buckets will be used.
+You can always rehash the map with `cxMapRehash()` to change the number of buckets to something more efficient,
+but you need to be careful, because when you use this function you are effectively locking into using this
+specific hash map implementation, and you would need to remove all calls to this function when you want to
+exchange the concrete map implementation with something different.
+
 ## Utilities
 
 *Header file:* [utils.h](api/utils_8h.html)