From 6bcbaeb98ee92f0b5d69bc5b4641a055ef08732b Mon Sep 17 00:00:00 2001
From: Danny Robson <danny@nerdcruft.net>
Date: Sat, 15 Dec 2018 15:36:28 +1100
Subject: [PATCH] bitwise: slight improvements to documentation

---
 bitwise.hpp | 26 ++++++++++++++++++++++----
 1 file changed, 22 insertions(+), 4 deletions(-)

diff --git a/bitwise.hpp b/bitwise.hpp
index ec31a78e..3b1d098f 100644
--- a/bitwise.hpp
+++ b/bitwise.hpp
@@ -18,24 +18,37 @@
 
 namespace cruft {
     ///////////////////////////////////////////////////////////////////////////
+    /// Rotate `value` left by `magnitude` bits.
+    ///
+    /// `magnitude` must not be greater than the bit count of `value`.
     template <typename T>
     constexpr T
     rotatel [[gnu::pure]] (const T value, std::size_t magnitude)
     {
+        CHECK_LE (magnitude, sizeof (value) * 8);
+
         return (value << magnitude) | (value >> (sizeof (value) * 8 - magnitude));
     }
 
 
+    ///------------------------------------------------------------------------
+    /// Rotate `value` right by `magnitude` bits.
+    ///
+    /// `magnitude` must not be greater than the bit count of `value`.
     template <typename T>
     constexpr T
     rotater [[gnu::pure]] (const T value, std::size_t magnitude)
     {
+        CHECK_LE (magnitude, sizeof (value) * 8);
+
         return (value >> magnitude) | (value << (sizeof (value) * 8 - magnitude));
     }
 
 
     ///////////////////////////////////////////////////////////////////////////
-    // adapted from 'bit twiddling hacks'
+    /// Reverse the order of bits in the supplied value.
+    ///
+    /// Adapted from 'bit twiddling hacks'
     template <typename T>
     constexpr
     std::enable_if_t<std::is_integral<T>::value, T>
@@ -56,7 +69,9 @@ namespace cruft {
 
 
     ///////////////////////////////////////////////////////////////////////////
-    // adapted from 'bit twiddling hacks'
+    /// Reverse the order of bits in the supplied value.
+    ///
+    /// Adapted from 'bit twiddling hacks'
     template <>
     constexpr
     uint8_t
@@ -67,6 +82,7 @@ namespace cruft {
 
 
     ///////////////////////////////////////////////////////////////////////////
+    /// Calculates the number of bits that are set.
     constexpr unsigned
     popcount (unsigned t)
     {
@@ -74,7 +90,8 @@ namespace cruft {
     }
 
 
-    //-------------------------------------------------------------------------
+    ///------------------------------------------------------------------------
+    /// Calculates the number of bits that are set.
     constexpr unsigned long
     popcount (unsigned long t)
     {
@@ -82,7 +99,8 @@ namespace cruft {
     }
 
 
-    //-------------------------------------------------------------------------
+    ///------------------------------------------------------------------------
+    /// Calculates the number of bits that are set.
     constexpr unsigned long long
     popcount (unsigned long long t)
     {