From 2bbe6dc90076f41ee06437688b094e435e685453 Mon Sep 17 00:00:00 2001
From: Danny Robson <danny@nerdcruft.net>
Date: Thu, 18 Oct 2018 17:12:18 +1100
Subject: [PATCH] tuple/type: commenting and style

---
 tuple/type.hpp | 53 ++++++++++++++++++++++++++++++++++----------------
 1 file changed, 36 insertions(+), 17 deletions(-)

diff --git a/tuple/type.hpp b/tuple/type.hpp
index 71135b23..6b4a1e9d 100644
--- a/tuple/type.hpp
+++ b/tuple/type.hpp
@@ -6,46 +6,62 @@
  * Copyright 2015-2018 Danny Robson <danny@nerdcruft.net>
  */
 
-#ifndef CRUFT_UTIL_TUPLE_TYPE_HPP
-#define CRUFT_UTIL_TUPLE_TYPE_HPP
-
 #include "../types.hpp"
 
 #include "../types/traits.hpp"
 
 #include <cstddef>
 #include <tuple>
+#include <functional>
 
 
 namespace cruft::tuple::type {
     ///////////////////////////////////////////////////////////////////////////
-    /// call a provided FunctorT with type_tag<T> for each type in the
-    /// tuple-like type TupleT.
+    /// Invoke a provided FunctorT with the provided arguments and a
+    /// type_tag<T> for each type in the tuple-like type TupleT.
+    ///
+    /// The order of invocation is low-index to high-index (left to right).
+    ///
+    /// \tparam TupleT      A tuple-like type
+    /// \tparam FunctorT    An invokable type
+    /// \tparam S           The index to be invoked; this is private.
+    /// \tparam ArgsT       User supplied arguments
     template<
         typename TupleT,
         typename FunctorT,
-        size_t S = 0
+        size_t S = 0,
+        typename ...ArgsT
     >
     void
-    each (FunctorT &&func)
+    each (FunctorT &&func, ArgsT &&...args)
     {
+        /// Get a handle on the type we need to forward.
         static_assert (S < std::tuple_size_v<TupleT>);
         using value_type = typename std::tuple_element<S,TupleT>::type;
 
-        func (cruft::type_tag<value_type> {});
+        /// Call the user's invokable.
+        std::invoke (func, args..., cruft::type_tag<value_type> {});
 
+        /// Recurse into ourselves with a higher index if we haven't reached
+        /// the end.
         if constexpr (S + 1 < std::tuple_size_v<TupleT>) {
-            each<TupleT,FunctorT,S+1> (std::forward<FunctorT> (func));
+            each<TupleT,FunctorT,S+1> (
+                std::forward<FunctorT> (func),
+                std::forward<ArgsT> (args)...
+            );
         }
     }
 
 
     ///////////////////////////////////////////////////////////////////////////////
-    /// Statically map the member types of a tuple via F<>::type
+    /// Convert a tuple-type holding an initial set of types into a tuple-type
+    /// holding a different set of types using the supplied transform:
+    ///     `FieldT<...>`.
     ///
-    /// TupleT: tuple type
-    /// FieldT: type mapping object, conversion uses FieldT<>::type
-    /// Indices: tuple indexing helper
+    /// \tparam TupleT  The initial tuple-type
+    /// \tparam FieldT  The type-transform type.
+    ///                 The conversion uses FieldT<...>::type to perform the
+    ///                 conversions.
     template <
         typename TupleT,
         template <
@@ -80,11 +96,16 @@ namespace cruft::tuple::type {
 
 
     ///////////////////////////////////////////////////////////////////////////
-    /// query the index of the first occurrence of type `T' in the tuple-like
+    /// Query the index of the first occurrence of type `T' in the tuple-like
     /// type `TupleT'.
     ///
-    /// if the query type does not occur in the tuple type a compiler error
+    /// If the query type does not occur in the tuple type a compiler error
     /// should be generated.
+    ///
+    /// \tparam TupleT  The tuple-type to be queried
+    /// \tparam ValueT  The value-type we are searching for
+    ///
+    /// The index will be defined as the size_t `::value` if it has been found.
     template<
         typename TupleT,
         typename ValueT,
@@ -289,5 +310,3 @@ namespace cruft::tuple::type {
     template <typename T>
     using unique_t = typename unique<T>::type;
 }
-
-#endif