From 510603873421c87a0f2b562de553b46588a76e6c Mon Sep 17 00:00:00 2001
From: Danny Robson <danny@nerdcruft.net>
Date: Tue, 10 Sep 2019 14:46:55 +1000
Subject: [PATCH] list: add more comments

---
 list/sort.hpp | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/list/sort.hpp b/list/sort.hpp
index 854cd322..3fc735d6 100644
--- a/list/sort.hpp
+++ b/list/sort.hpp
@@ -16,6 +16,9 @@
 #include <utility>
 
 namespace cruft::list {
+    /// Return the total number of nodes in the list
+    ///
+    /// It is safe to call this function with a null node pointer.
     template <typename NodeT>
     std::size_t
     size (NodeT const *head)
@@ -149,7 +152,14 @@ namespace cruft::list {
     }
 
 
-    /// An in-place merge sort for singly linked lists.
+    /// Sort a linked list using a supplied comparator.
+    ///
+    /// The current implementation uses an in-place merge sort.
+    ///
+    /// Each nodes successor may be modified, but the data will not be.
+    ///
+    /// Returns the head of the newly sorted list. The caller _must_ reset
+    /// their stored head node with this value otherwise data may be lost.
     template <typename NodeT, typename ComparatorT>
     NodeT*
     sort [[nodiscard]] [[using gnu: nonnull, returns_nonnull]] (
@@ -170,6 +180,7 @@ namespace cruft::list {
     }
 
 
+    /// Sort a linked list using the default (value) comparator.
     template <typename NodeT>
     NodeT*
     sort [[nodiscard]] [[using gnu: nonnull, returns_nonnull]] (