From: Davin McCall <davmac@davmac.org>
Date: Mon, 26 Jun 2017 08:32:40 +0000 (+0100)
Subject: Improve code documentation.
X-Git-Tag: v0.06~43
X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=a74ca3f5b42f9b670b333804ce17c5255553ca03;p=oweals%2Fdinit.git

Improve code documentation.
---

diff --git a/src/dinit-ll.h b/src/dinit-ll.h
index 267cd51..101aa3f 100644
--- a/src/dinit-ll.h
+++ b/src/dinit-ll.h
@@ -3,8 +3,12 @@
 
 // Simple single- and doubly-linked list implementation, where the contained element includes the
 // list node. This allows a single item to be a member of several different kinds of list, without
-// requiring dynamic allocation of nodes.
+// requiring dynamic allocation of nodes for the different lists.
+//
+// To accomplish this without abstraction penalty, the function to retrieve the list node from the
+// element is specified as the second template parameter.
 
+// Doubly-linked list node:
 template <typename T>
 struct lld_node
 {
@@ -12,14 +16,17 @@ struct lld_node
     T * prev = nullptr;
 };
 
+// Singly-linked list node:
 template <typename T>
 struct lls_node
 {
     T * next = nullptr;
 };
 
-// list is circular, so first->prev = tail.
-
+// Doubly-linked list implementation. The list is circular, so 'first->prev' yields the tail of
+// the list, though we still need to special-case the empty list (where first == nullptr).
+// next/prev pointers in a node are set to nullptr when the node is not linked into a list
+// (and are never equal to nullptr when the node is linked into a list).
 template <typename T, lld_node<T> &(*E)(T *)>
 class dlist
 {
@@ -106,11 +113,11 @@ class dlist
     }
 };
 
+// Singly-linked list implementation.
 template <typename T, lls_node<T> &(*E)(T *)>
 class slist
 {
     T * first;
-    // E extractor;
 
     public:
     slist() noexcept : first(nullptr) { }