From 56d4784b117529dc4382d5261ea91c771e04cc2d Mon Sep 17 00:00:00 2001
From: Max Kellermann <mk@cm4all.com>
Date: Tue, 23 Apr 2024 19:55:12 +0200
Subject: [PATCH] util/IntrusiveList: add API documentation

---
 src/util/IntrusiveList.hxx | 22 ++++++++++++++++++++--
 1 file changed, 20 insertions(+), 2 deletions(-)

diff --git a/src/util/IntrusiveList.hxx b/src/util/IntrusiveList.hxx
index f222ec318..f47ef266e 100644
--- a/src/util/IntrusiveList.hxx
+++ b/src/util/IntrusiveList.hxx
@@ -13,7 +13,14 @@
 #include <type_traits>
 #include <utility>
 
+/**
+ * Template parameter for #IntrusiveList with compile-time options.
+ */
 struct IntrusiveListOptions {
+	/**
+	 * @param constant_time_size make size() constant-time by caching the
+	 * number of items in a field?
+	 */
 	bool constant_time_size = false;
 
 	/**
@@ -147,8 +154,7 @@ struct IntrusiveListMemberHookTraits {
 };
 
 /**
- * @param constant_time_size make size() constant-time by caching the
- * number of items in a field?
+ * An intrusive doubly-linked circular list.
  */
 template<typename T,
 	 typename HookTraits=IntrusiveListBaseHookTraits<T>,
@@ -269,6 +275,9 @@ public:
 			return std::distance(begin(), end());
 	}
 
+	/**
+	 * Remove all items from the linked list.
+	 */
 	void clear() noexcept {
 		if constexpr (GetHookMode() >= IntrusiveHookMode::TRACK) {
 			/* for SafeLinkIntrusiveListHook, we need to
@@ -282,6 +291,9 @@ public:
 		}
 	}
 
+	/**
+	 * Like clear(), but invoke a disposer function on each item.
+	 */
 	void clear_and_dispose(Disposer<value_type> auto disposer) noexcept {
 		bool is_empty = empty();
 
@@ -299,6 +311,12 @@ public:
 	}
 
 	/**
+	 * Remove all items matching the given predicate and invoke
+	 * the given disposer on it.
+	 *
+	 * Neither the predicate nor the disposer are allowed to
+	 * modify the list (or destruct it).
+	 *
 	 * @return the number of removed items
 	 */
 	std::size_t remove_and_dispose_if(std::predicate<const_reference> auto pred,