From 6578796777a198bec086be7687d018346aca85f1 Mon Sep 17 00:00:00 2001
From: Zang MingJie <mingjiez@google.com>
Date: Wed, 5 Jan 2022 10:34:04 +0800
Subject: [PATCH] Improve comments

---
 src/lib/support/IntrusiveList.h | 40 +++++++++++++--------------------
 1 file changed, 15 insertions(+), 25 deletions(-)

diff --git a/src/lib/support/IntrusiveList.h b/src/lib/support/IntrusiveList.h
index 998cf2851e1f56..9dc773e97531af 100644
--- a/src/lib/support/IntrusiveList.h
+++ b/src/lib/support/IntrusiveList.h
@@ -131,14 +131,14 @@ class IntrusiveListBase
 protected:
     // The list is formed as a ring with mNode being the end.
     //
-    // begin                   end
-    //   v                      v
-    // item -> item -> ... -> mNode
-    //   ^                      |
-    //    \--------------------/
+    // begin                                        end
+    //   v                                           v
+    // item(first) -> item -> ... -> item(last) -> mNode
+    //   ^                                           |
+    //    \------------------------------------------/
     //
     IntrusiveListBase() : mNode(&mNode, &mNode) {}
-    ~IntrusiveListBase() { mNode.Remove(); }
+    ~IntrusiveListBase() { mNode.Remove(); /* clear mNode such that the destructor checking mNode.IsInList doesn't fail */ }
 
     IteratorBase begin() { return IteratorBase(mNode.mNext); }
     IteratorBase end() { return IteratorBase(&mNode); }
@@ -146,23 +146,9 @@ class IntrusiveListBase
     void PushFront(IntrusiveListNodeBase * node) { mNode.Append(node); }
     void PushBack(IntrusiveListNodeBase * node) { mNode.Prepend(node); }
 
-    void InsertBefore(IteratorBase pos, IntrusiveListNodeBase * node)
-    {
-        VerifyOrDie(pos.mCurrent->IsInList());
-        pos.mCurrent->Prepend(node);
-    }
-
-    void InsertAfter(IteratorBase pos, IntrusiveListNodeBase * node)
-    {
-        VerifyOrDie(pos.mCurrent->IsInList());
-        pos.mCurrent->Append(node);
-    }
-
-    void Remove(IntrusiveListNodeBase * node)
-    {
-        VerifyOrDie(Contains(node));
-        node->Remove();
-    }
+    void InsertBefore(IteratorBase pos, IntrusiveListNodeBase * node) { pos.mCurrent->Prepend(node); }
+    void InsertAfter(IteratorBase pos, IntrusiveListNodeBase * node) { pos.mCurrent->Append(node); }
+    void Remove(IntrusiveListNodeBase * node) { node->Remove(); }
 
     bool Contains(IntrusiveListNodeBase * node)
     {
@@ -187,6 +173,12 @@ class IntrusiveListBaseHook
     static IntrusiveListNodeBase * ToNode(T * object) { return static_cast<IntrusiveListNodeBase *>(object); }
 };
 
+/**
+ * @brief An intrusive double linked list.
+ *
+ * @tparam T    Type of element in the list.
+ * @tparam Hook A hook to convert between object T and the IntrusiveListNodeBase
+ */
 template <typename T, typename Hook = IntrusiveListBaseHook<T>>
 class IntrusiveList : public IntrusiveListBase
 {
@@ -215,8 +207,6 @@ class IntrusiveList : public IntrusiveListBase
     void InsertAfter(Iterator pos, T * value) { IntrusiveListBase::InsertAfter(pos, Hook::ToNode(value)); }
     void Remove(T * value) { IntrusiveListBase::Remove(Hook::ToNode(value)); }
     bool Contains(T * value) { return IntrusiveListBase::Contains(Hook::ToNode(value)); }
-
-private:
 };
 
 } // namespace chip