list: add more comments

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]] (