build: add doxygen comments for various headers

adapter.hpp

@@ -3,21 +3,25 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
  *
- * Copyright 2015 Danny Robson <danny@nerdcruft.net>
+ * Copyright 2015-2018 Danny Robson <danny@nerdcruft.net>
  */
 
-#ifndef __UTIL_ADAPTER_HPP
-#define __UTIL_ADAPTER_HPP
-
 #include <array>
 #include <cstddef>
 #include <iterator>
 
+
 namespace cruft::adapter {
     namespace container {
-        // reverse a container for range-based-for
+        /// Creates a reversed proxy for a referenced container.
+        ///
+        /// The target container must remain an l-value.
+        ///
+        /// It is the caller's job to ensure the targeted container remains
+        /// valid for the duration of the proxy's lifetime.
         template <typename T>
-        struct reverse {
+        class reverse {
+        public:
             explicit reverse (T &_target):
                 m_target (_target)
             { ; }
@@ -36,114 +40,81 @@ namespace cruft::adapter {
         };
 
 
+        //---------------------------------------------------------------------
         template <typename Container>
-        auto
+        reverse (Container&) -> reverse<Container>;
-        make_reverse (Container &c)
-        {
-            return reverse<Container> { c };
-        };
 
 
-        // adapt a container's range methods to return indices rather than iterators
+        ///////////////////////////////////////////////////////////////////////
+        /// Adapter's a container to return indices of the container's data
+        /// rather than the values themselves.
+        ///
+        /// The targeted container must be an l-value.
+        ///
+        /// It is the caller's job to ensure the targeted container remains
+        /// valid for the duration of the proxy's lifetime.
         template <typename T>
-        struct indices {
+        class indices {
+        public:
             using typename T::size_type;
 
             explicit indices (T &_target):
                 m_target (_target)
             { ; }
 
-            size_type begin (void) { return 0; }
+            size_type begin (void)& { return 0; }
-            size_type end   (void) { return m_target.size (); }
+            size_type end   (void)& { return m_target.size (); }
 
         private:
-            T m_target;
+            T &m_target;
         };
     }
 
+
     namespace iterator {
-        // adapt an iterator to return the n-th tuple element of the
+        ///////////////////////////////////////////////////////////////////////
-        // underlying iterator::value_type
+        /// Adapt's an iterator to return the n-th element of the tuple that
-        template <size_t I, typename It>
+        /// corresponds to the underlying iterator::value_type when
+        /// dereferenced.
+        template <size_t I, typename IteratorT>
         struct scalar : public std::iterator<
-            typename std::iterator_traits<It>::iterator_category,
+            typename std::iterator_traits<IteratorT>::iterator_category,
             typename std::tuple_element<
                 I,
                 typename std::iterator_traits<
-                    It
+                    IteratorT
                 >::value_type
             >::type,
-            typename std::iterator_traits<It>::difference_type
+            typename std::iterator_traits<IteratorT>::difference_type
         > {
         public:
-            using reference  = typename std::iterator_traits<scalar<I,It>>::reference;
+            using inner_type = typename std::iterator_traits<IteratorT>::value_type;
-            using value_type = typename std::iterator_traits<scalar<I,It>>::value_type;
 
-            explicit scalar (It _inner):
+            using value_type = decltype (std::get<I> (std::declval<inner_type>));
+            using reference  = value_type&;
+
+
+            explicit scalar (IteratorT _inner):
                 m_inner (_inner)
             { ; }
 
-            const reference operator* (void) const
+
+            const reference operator* (void) const&
             { return std::get<I> (*m_inner); }
 
-            reference operator* (void)
+            reference operator* (void)&
             { return std::get<I> (*m_inner); }
 
-            bool operator== (scalar<I,It> rhs) { return m_inner == rhs.m_inner; }
+            bool operator== (scalar<I,IteratorT> rhs) { return m_inner == rhs.m_inner; }
-            bool operator!= (scalar<I,It> rhs) { return m_inner != rhs.m_inner; }
+            bool operator!= (scalar<I,IteratorT> rhs) { return m_inner != rhs.m_inner; }
 
-            scalar<I,It>& operator++ (void)
+
+            scalar<I,IteratorT>& operator++ (void)
             { ++m_inner; return *this; }
 
+
         private:
-            It m_inner;
+            IteratorT m_inner;
         };
-
-
-        //template <
-        //    typename It,
-        //    size_t S,
-        //    typename T
-        //>
-        //struct explode : public std::enable_if<
-        //    std::is_same<
-        //        typename std::iterator_traits<It>::value_type,
-        //        std::array<T,S>
-        //    >::value,
-        //    typename std::iterator<
-        //        typename std::iterator_traits<It>::iterator_category,
-        //        typename std::tuple_element<
-        //            typename std::iterator_traits<It>::value_type
-        //        >::type,
-        //        typename std::iterator_traits<It>::difference_type
-        //    >::type
-        //> {
-        //public:
-        //    explode (It _inner):
-        //        m_inner (_inner),
-        //        m_sequence (0)
-        //    { ; }
-
-        //    const reference operator* (void) const
-        //    { return (*m_inner)[m_seqence]; }
-
-        //    reference operator* (void)
-        //    { return (*m_inner)[m_seqence]; }
-
-        //    bool operator== (explode rhs) { return m_inner == rhs.m_inner && m_sequence == rhs.m_sequence; }
-        //    bool operator!= (explode rhs) { return !(*this == rhs); }
-
-        //    explode<It>& operator++ (void)
-        //    {
-        //        if (++m_sequence >= S)
-        //            ++m_inner;
-        //    }
-
-        //private:
-        //    It m_inner;
-        //    size_t m_sequence;
-        //};
     }
 }
-
-#endif

annotation.hpp

@@ -3,12 +3,30 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
  *
- * Copyright 2011 Danny Robson <danny@nerdcruft.net>
+ * Copyright 2011-2018 Danny Robson <danny@nerdcruft.net>
  */
 
-#ifndef __UTIL_ANNOTATION_HPP
+#pragma once
-#define __UTIL_ANNOTATION_HPP
 
+#include <type_traits>
+
+
+///////////////////////////////////////////////////////////////////////////////
+/// Forwards the supplied `value` and annotates the result as likely to be the
+/// value `typical`.
+///
+/// Must be an integral type.
+template <typename T, typename = std::enable_if_t<std::is_integral_v<T>>>
+constexpr inline
+T
+expect (T val, T typical)
+{
+    return __builtin_expect (val, typical);
+}
+
+
+/// Coerces the argument into a bool and annotates the result as likely to be
+/// true.
 template <typename T>
 constexpr inline
 bool
@@ -16,19 +34,10 @@ likely (T &&t)
 { return __builtin_expect (!!t, true); }
 
 
+/// Coerces the argument into a bool and annotates the result as likely to be
+/// false.
 template <typename T>
 constexpr inline
 bool
 unlikely (T &&t)
 { return __builtin_expect (!!t, false); }
-
-
-constexpr inline
-long
-expect (long val, long typical)
-{
-    return __builtin_expect (val, typical);
-}
-
-
-#endif

ascii.hpp

@@ -6,8 +6,7 @@
  * Copyright 2016-2018 Danny Robson <danny@nerdcruft.net>
  */
 
-#ifndef CRUFT_UTIL_ASCII_HPP
+#pragma once
-#define CRUFT_UTIL_ASCII_HPP
 
 #include "annotation.hpp"
 
@@ -16,6 +15,7 @@
 
 namespace cruft::ascii {
     ///////////////////////////////////////////////////////////////////////////
+    /// Returns true if the supplied character is an ASCII digit.
     constexpr inline
     bool
     is_digit (char c) noexcept
@@ -23,7 +23,10 @@ namespace cruft::ascii {
         return c >= '0' && c <= '9';
     }
 
-    //-------------------------------------------------------------------------
+    ///------------------------------------------------------------------------
+    /// Converts an ASCII character into a corresponding integer.
+    ///
+    /// Specifically does not convert multiple characters.
     constexpr inline
     uint8_t
     to_integer (char c)
@@ -34,7 +37,9 @@ namespace cruft::ascii {
     }
 
 
-    //-------------------------------------------------------------------------
+    ///------------------------------------------------------------------------
+    /// Returns true if the supplied character is an upper case letter in the
+    /// "C" locale.
     constexpr inline
     bool
     is_upper (char c) noexcept
@@ -43,7 +48,9 @@ namespace cruft::ascii {
     }
 
 
-    //-------------------------------------------------------------------------
+    ///------------------------------------------------------------------------
+    /// Returns true if the supplied character is a lower case letter in the
+    /// "C" locale.
     constexpr inline
     bool
     is_lower (char c) noexcept
@@ -52,7 +59,9 @@ namespace cruft::ascii {
     }
 
 
-    //-------------------------------------------------------------------------
+    ///------------------------------------------------------------------------
+    /// Returns true if the supplied character is an alphabetical character in
+    /// the "C" locale.
     constexpr inline
     bool
     is_alpha (char c) noexcept
@@ -61,7 +70,8 @@ namespace cruft::ascii {
     }
 
 
-    //-------------------------------------------------------------------------
+    ///------------------------------------------------------------------------
+    /// Returns true if the supplied ASCII character is a hexadecimal digit.
     constexpr inline
     bool
     is_hex (const char c) noexcept
@@ -76,7 +86,11 @@ namespace cruft::ascii {
     }
 
 
-    //-------------------------------------------------------------------------
+    ///------------------------------------------------------------------------
+    /// Converts a supplied ASCII character from a hexadecimal digit into a
+    /// corresponding integer.
+    ///
+    /// Explicitly does not cover any multi-character case.
     constexpr inline
     uint8_t
     from_hex (char c)
@@ -89,24 +103,35 @@ namespace cruft::ascii {
 
 
     ///////////////////////////////////////////////////////////////////////////
+    /// Converts a lower case ASCII character into an upper case character.
+    ///
+    /// The results are undefined if the character isn't a lowercase
+    /// alphabetical character in the "C" locale.
     constexpr inline
     char
     to_upper (char c) noexcept
     {
+        CHECK (is_lower (c));
         return c - 'a' + 'A';
     }
 
 
-    //-------------------------------------------------------------------------
+    ///------------------------------------------------------------------------
+    /// Converts an upper case ASCII character into a lower case character.
+    ///
+    /// The results are undefined if the character isn't an uppercase
+    /// alphabetical character in the "C" locale.
     constexpr inline
     char
     to_lower (char c) noexcept
     {
+        CHECK (is_upper (c));
         return c - 'A' + 'a';
     }
 
 
     ///////////////////////////////////////////////////////////////////////////
+    /// Returns true if the supplied ASCII character is whitespace.
     constexpr inline
     bool
     is_space (char c)
@@ -131,7 +156,9 @@ namespace cruft::ascii {
 #include "debug.hpp"
 #include <vector>
 
-/// convert an ascii string of hex digits into a vector of uint8
+/// Converts a string of ASCII hex digits into a vector of u08 values.
+///
+/// The supplied string must have a length that is a multiple of 2.
 std::vector<std::uint8_t>
 inline
 operator"" _hex2u8 (const char *str, size_t len)
@@ -146,6 +173,9 @@ operator"" _hex2u8 (const char *str, size_t len)
 
 
 ///////////////////////////////////////////////////////////////////////////////
+/// Converts a string of ASCII hex digits into an array of u08 values.
+///
+/// The supplied string must have a length that is a multiple of 2.
 template <typename CharT, CharT ...StrV>
 constexpr auto
 operator"" _hex2array (void)
@@ -161,5 +191,3 @@ operator"" _hex2array (void)
 
     return res;
 }
-
-#endif

bitwise.hpp

@@ -6,8 +6,7 @@
  * Copyright 2011-2018 Danny Robson <danny@nerdcruft.net>
  */
 
-#ifndef CRUFT_UTIL_BITWISE_HPP
+#pragma once
-#define CRUFT_UTIL_BITWISE_HPP
 
 #include "types/bits.hpp"
 #include "debug.hpp"
@@ -128,6 +127,22 @@ namespace cruft {
     }
 
 
+    /// A convenience wrapper that provides access to a range of bits in an
+    /// underlying integral value.
+    ///
+    /// This class is most useful as part of a union where each has differing
+    /// offsets and sizes that cover the underlying type.
+    ///
+    /// A conversion operator is supplied for accessing the bit value.
+    ///
+    /// ValueT must support bit shifting and bitwise operators (primarily
+    /// bitwise and).
+    ///
+    /// \tparam ValueT   the underlying integral type
+    /// \tparam OffsetV  the index of the first bit of the range (where 0 is
+    ///                  most significant)
+    /// \tparam SizeV    the number of bits in the range. Must be strictly
+    ///                  positive.
     template <
         typename ValueT,
         size_t OffsetV,
@@ -137,8 +152,10 @@ namespace cruft {
     public:
         static_assert (SizeV > 0);
         static_assert (OffsetV + SizeV <= sizeof (ValueT) * 8);
+        static_assert (sizeof (ValueT) == sizeof (bitfield));
 
-        decltype(auto) operator+ () const { return +value; }
+        decltype(auto)
+        operator+ () const { return +value; }
 
         operator auto() const
         {
@@ -157,6 +174,4 @@ namespace cruft {
     {
         return os << +ValueT(val);
     }
-};
+}
-
-#endif

cast.hpp

@@ -62,10 +62,13 @@ namespace cruft::cast {
 
 
     ///////////////////////////////////////////////////////////////////////////
-    // cast to a smaller type of the same signedness and realness and assert
+    /// Cast to a smaller type of the same signedness and realness and assert
-    // that both values are still equal.
+    /// that both values are still equal.
-    //
+    ///
-    // checks will be compiled out if NDEBUG is defined.
+    /// Any runtime checks will be compiled out if NDEBUG is defined.
+    ///
+    /// Identity casts are allowed so as to simplify the use of this routine
+    /// in template code.
     template <
         typename NarrowT,
         typename WideT,
@@ -94,9 +97,10 @@ namespace cruft::cast {
 
 
     ///////////////////////////////////////////////////////////////////////////
-    // cast between types checking that equality holds with the result
+    /// Cast between types checking that exact equality holds if the result is
-    //
+    /// casted back to the original type.
-    // checks will be compiled out if NDEBUG is defined.
+    ///
+    /// Runtime checks will be compiled out if NDEBUG is defined.
     template <typename DstT, typename SrcT>
     constexpr DstT
     lossless (const SrcT &src)
@@ -131,7 +135,7 @@ namespace cruft::cast {
 
 
     ///////////////////////////////////////////////////////////////////////////
-    /// assert if the value is not a pointer to a subclass of T, else return
+    /// Assert if the value is not a pointer to a subclass of T, else return
     /// the converted value. Note: this is only a debug-time check and is
     /// compiled out in optimised builds.
     template <
@@ -160,8 +164,10 @@ namespace cruft::cast {
 
 
     ///////////////////////////////////////////////////////////////////////////
-    /// cast a pointer from one type to another, asserting that the required
+    /// Cast a pointer from one type to another, asserting that the required
     /// alignment of the destination type has been satisfied.
+    ///
+    /// Runtime checks will be compiled out if NDEBUG is defined.
     template <
         typename DstT,
         typename SrcT,
@@ -179,7 +185,7 @@ namespace cruft::cast {
 
 
     ///////////////////////////////////////////////////////////////////////////
-    /// cast from SrcT to DstT and damn any consequences.
+    /// Cast from SrcT to DstT and damn any consequences; just make it compile.
     template <typename DstT, typename SrcT>
     DstT ffs (SrcT src)
     {

cpuid_x86.hpp

@@ -6,14 +6,14 @@
  * Copyright 2018 Danny Robson <danny@nerdcruft.net>
  */
 
-#ifndef CRUFT_UTIL_CPUID_X86_HPP
+#pragma once
-#define CRUFT_UTIL_CPUID_X86_HPP
 
 #include "cpuid.hpp"
 
 #include <array>
 
 namespace cruft::cpu {
+    /// Queries x86 CPU features using the CPUID instruction.
     struct x86 {
         x86 ();
 
@@ -44,5 +44,3 @@ namespace cruft::cpu {
     std::ostream&
     operator<< (std::ostream&, const cruft::cpu::x86&);
 };
-
-#endif

quaternion.hpp

@@ -19,32 +19,44 @@
 
 
 namespace cruft {
-    // quaternion's are _just_ different enough to other coord types that we
+    /// Represents a quaternion value.
-    // special case as a distinct POD type and provide many of the same
+    ///
-    // functions as distinct declarations.
+    /// Quaternion's are _just_ different enough to other coord types that we
-    //
+    /// special case as a distinct POD type and provide many of the same
-    // issues include:
+    /// functions as distinct declarations.
-    // * strictly 4 dimensions
+    ///
-    // * scalar operations sometimes don't make sense on the w component
+    /// Considerations include:
-    // * objects must be normalised to make sense
+    /// * strictly 4 dimensions
+    /// * scalar operations sometimes don't make sense on the w component
+    /// * objects must be normalised to make sense
     template <typename T>
     struct quaternion {
         T w, x, y, z;
 
         static constexpr std::size_t size (void) { return 4; }
 
+        /// Construct a quaternion that represents a rotation of `radians`
+        /// around the unit-vector `axis`.
         static quaternion angle_axis (T radians, vector<3,T> axis);
+
+        /// Construct a quaternion that represents a sequence of euler angle
+        /// rotations in radians. Equivalent to the concatentation of x, y,
+        /// and then z rotations.
         static quaternion from_euler (vector<3,T>);
 
-        /// build a quaternion that represents the rotation from a to b
+        /// Constructs a quaternion that represents the rotation of a unit
+        /// vector `a` to the unit vector `b`.
         static quaternion from_to (vector<3,T> a, vector<3,T> b);
 
-        /// build a quaternion that represents the rotation needed to look at
+        /// Constructs a quaternion that represents the rotation needed to
-        /// a direction with a given up direction
+        /// look along the unit vector `fwd` with the unit vector `up`
+        /// denoting the upward direction.
         static quaternion look (vector<3,T> fwd, vector<3,T> up);
 
+        /// Converts a rotation quaternion into an equivalent matrix form.
         matrix4<T> as_matrix (void) const;
 
+        /// Constructs a identity rotation quaternion.
         static constexpr
         quaternion<T>
         identity (void)
@@ -62,12 +74,15 @@ namespace cruft {
 
 
     ///////////////////////////////////////////////////////////////////////////
+    /// Returns the result of rotating the unit vector `dir` using the
+    /// quaternion `q`.
     template <typename T>
     vector3<T>
-    rotate (vector3<T>, quaternion<T>);
+    rotate (vector3<T> dir, quaternion<T> q);
 
 
-    //-------------------------------------------------------------------------
+    ///------------------------------------------------------------------------
+    /// Returns the result of rotating the unit vector `v` by the quaternion `q`.
     template <typename T>
     vector3<T>
     operator* (quaternion<T> const q, vector3<T> const v)
@@ -77,6 +92,7 @@ namespace cruft {
 
 
     ///////////////////////////////////////////////////////////////////////////
+    /// Returns the square of the L2 norm of the quaternion `q`.
     template <typename T>
     constexpr
     T
@@ -89,7 +105,8 @@ namespace cruft {
     }
 
 
-    //-------------------------------------------------------------------------
+    ///------------------------------------------------------------------------
+    /// Returns the L2 norm of the quaternion `q`.
     template <typename T>
     constexpr
     T
@@ -99,7 +116,8 @@ namespace cruft {
     }
 
 
-    //-------------------------------------------------------------------------
+    ///------------------------------------------------------------------------
+    /// Returns true if the quaternion has a unit L2 norm.
     template <typename T>
     constexpr
     bool
@@ -109,7 +127,8 @@ namespace cruft {
     }
 
 
-    //-------------------------------------------------------------------------
+    ///------------------------------------------------------------------------
+    /// Returns the normalised form of quaternion `q`.
     template <typename T>
     constexpr
     quaternion<T>