doc: document pw_map

Take some parts out of the public documentation, add a lot of internal
documentation to make it easier for the next person to figure out how
this works.

The use of static inline prevents doxygen from generating docs, put a
note in to link to the header file directly.

src/pipewire/map.h

@@ -37,7 +37,25 @@ extern "C" {
 
 /** \defgroup pw_map Map
  *
- * \brief A map that holds objects indexed by id
+ * \brief A map that holds pointers to objects indexed by id
+ *
+ * The map is a sparse version of the \ref pw_array "pw_array" that manages the
+ * indices of elements for the caller. Adding items with
+ * pw_map_insert_new() returns the assigned index for that item; if items
+ * are removed the map re-uses indices to keep the array at the minimum
+ * required size.
+ *
+ * \code{.c}
+ * struct pw_map map = PW_MAP_INIT(4);
+ *
+ * idx1 = pw_map_insert_new(&map, ptr1);
+ * idx2 = pw_map_insert_new(&map, ptr2);
+ * // the map is now [ptr1, ptr2], size 2
+ * pw_map_remove(&map, idx1);
+ * // the map is now [<unused>, ptr2], size 2
+ * pw_map_insert_new(&map, ptr3);
+ * // the map is now [ptr3, ptr2], size 2
+ * \endcode
  */
 
 /**
@@ -45,25 +63,43 @@ extern "C" {
  * \{
  */
 
-/** An entry in the map */
+/** \private
+ * An entry in the map. This is used internally only. Each element in the
+ * backing pw_array is a union pw_map_item. For real items, the data pointer
+ * points to the item. If an element has been removed, pw_map->free_list
+ * is the index of the most recently removed item. That item contains
+ * the index of the next removed item until item->next is SPA_ID_INVALID.
+ *
+ * The free list is prepended only, the last item to be removed will be the
+ * first item to get re-used on the next insert.
+ */
 union pw_map_item {
-	uint32_t next;	/**< next free index */
-	void *data;	/**< data of this item, must be an even address */
+	uint32_t next;	/* next free index */
+	void *data;	/* data of this item, must be an even address */
 };
 
-/** A map */
+/** A map. This struct should be treated as opaque by the caller. */
 struct pw_map {
-	struct pw_array items;	/**< an array with the map items */
-	uint32_t free_list;	/**< the free items */
+	struct pw_array items;	/* an array with the map items */
+	uint32_t free_list;	/* first free index */
 };
 
+/** \param extend the amount of bytes to grow the map with when needed */
 #define PW_MAP_INIT(extend) (struct pw_map) { PW_ARRAY_INIT(extend), SPA_ID_INVALID }
 
+/**
+ * Get the number of currently allocated elements in the map.
+ * \note pw_map_get_size() returns the currently allocated number of
+ * elements in the map, not the number of actually set elements.
+ * \return the number of available elements before the map needs to grow
+ */
 #define pw_map_get_size(m)            pw_array_get_len(&(m)->items, union pw_map_item)
 #define pw_map_get_item(m,id)         pw_array_get_unchecked(&(m)->items,id,union pw_map_item)
 #define pw_map_item_is_free(item)     ((item)->next & 0x1)
 #define pw_map_id_is_free(m,id)       (pw_map_item_is_free(pw_map_get_item(m,id)))
+/** \return true if the id fits within the current map size */
 #define pw_map_check_id(m,id)         ((id) < pw_map_get_size(m))
+/** \return true if there is a valid item at \a id  */
 #define pw_map_has_item(m,id)         (pw_map_check_id(m,id) && !pw_map_id_is_free(m, id))
 #define pw_map_lookup_unchecked(m,id) pw_map_get_item(m,id)->data
 
@@ -84,21 +120,24 @@ static inline void pw_map_init(struct pw_map *map, size_t size, size_t extend)
 	map->free_list = SPA_ID_INVALID;
 }
 
-/** Clear a map
- * \param map the map to clear
+/** Clear a map and free the data storage. All previously returned ids
+ * must be treated as invalid.
  */
 static inline void pw_map_clear(struct pw_map *map)
 {
 	pw_array_clear(&map->items);
 }
 
+/** Reset a map but keep previously allocated storage. All previously
+ * returned ids must be treated as invalid.
+ */
 static inline void pw_map_reset(struct pw_map *map)
 {
 	pw_array_reset(&map->items);
 	map->free_list = SPA_ID_INVALID;
 }
 
-/** Insert data in the map
+/** Insert data in the map. This function causes the map to grow if required.
  * \param map the map to insert into
  * \param data the item to add
  * \return the id where the item was inserted or SPA_ID_INVALID when the
@@ -111,7 +150,7 @@ static inline uint32_t pw_map_insert_new(struct pw_map *map, void *data)
 
 	if (map->free_list != SPA_ID_INVALID) {
 		start = (union pw_map_item *) map->items.data;
-		item = &start[map->free_list >> 1];
+		item = &start[map->free_list >> 1]; /* lsb always 1, see pw_map_remove */
 		map->free_list = item->next;
 	} else {
 		item = (union pw_map_item *) pw_array_add(&map->items, sizeof(union pw_map_item));
@@ -124,12 +163,12 @@ static inline uint32_t pw_map_insert_new(struct pw_map *map, void *data)
 	return id;
 }
 
-/** Insert data in the map at an index
- * \param map the map to inser into
- * \param id the index to insert at
+/** Replace the data in the map at an index.
+ *
+ * \param map the map to insert into
+ * \param id the index to insert at, must be less or equal to pw_map_get_size()
  * \param data the data to insert
- * \return 0 on success, -ENOSPC value when the index is invalid or a < 0
- *	errno value.
+ * \return 0 on success, -ENOSPC value when the index is invalid or a negative errno
  */
 static inline int pw_map_insert_at(struct pw_map *map, uint32_t id, void *data)
 {
@@ -162,7 +201,8 @@ static inline int pw_map_insert_at(struct pw_map *map, uint32_t id, void *data)
 	return 0;
 }
 
-/** Remove an item at index
+/** Remove an item at index. The id may get re-used in the future.
+ *
  * \param map the map to remove from
  * \param id the index to remove
  */