🧼🧽 Clean function signatures and doxygen (#19)

- Clean up function signatures, variable names, template names, and doxygen. 
- Move more details to detail folder and namespace.

Author: lukevalenty

include/cib/builder_meta.hpp

@@ -1,41 +1,33 @@
-#include "detail/compiler.hpp"
-
-#include <utility>
-
-
 #ifndef COMPILE_TIME_INIT_BUILD_BUILDER_META_HPP
 #define COMPILE_TIME_INIT_BUILD_BUILDER_META_HPP
 
 
 namespace cib {
+    /**
+     * Describe a builder to cib.
+     *
+     * @tparam BuilderType
+     *      The initial builder type cib should use when creating a builder.
+     *      This is only the initial type, the BuilderType::add(...) function
+     *      may return a different type and cib will track that correctly.
+     *
+     * @tparam InterfaceType
+     *      The type-erased interface services built with this builder
+     *      will implement. For example, cib::callback allows many other
+     *      callables to get executed when its service gets invoked. The
+     *      type-erased interface for cib::callback is a function pointer.
+     *
+     * @see cib::built
+     *
+     * @example cib::callback_meta
+     */
     template<
-        typename BuilderT,
-        typename InterfaceT>
+        typename BuilderType,
+        typename InterfaceType>
     struct builder_meta {
-        BuilderT builder();
-        InterfaceT interface();
+        BuilderType builder();
+        InterfaceType interface();
     };
-
-    namespace traits {
-        template<typename MetaT>
-        struct builder {
-            using type = decltype(std::declval<MetaT>().builder());
-        };
-
-        template<typename MetaT>
-        using builder_t = typename builder<MetaT>::type;
-
-        template<typename MetaT>
-        CIB_CONSTEXPR builder_t<MetaT> builder_v = {};
-
-        template<typename MetaT>
-        struct interface {
-            using type = decltype(std::declval<MetaT>().interface());
-        };
-
-        template<typename MetaT>
-        using interface_t = typename interface<MetaT>::type;
-    }
 }
 
 

include/cib/built.hpp

@@ -1,18 +1,21 @@
 #include "builder_meta.hpp"
-
+#include "detail/builder_traits.hpp"
 
 #ifndef COMPILE_TIME_INIT_BUILD_BUILT_HPP
 #define COMPILE_TIME_INIT_BUILD_BUILT_HPP
 
 
 namespace cib {
     /**
-     * Pointer to a concrete built service.
+     * Pointer to a built service implementation.
+     *
+     * @tparam ServiceMeta
+     *      Tag name of the service.
      *
-     * @tparam Tag Type name of the service.
+     * @see cib::builder_meta
      */
-    template<typename Tag>
-    traits::interface_t<Tag> built;
+    template<typename ServiceMeta>
+    traits::interface_t<ServiceMeta> service;
 }
 
 

include/cib/callback.hpp

@@ -12,41 +12,63 @@
 
 namespace cib {
     /**
-     * Extension point/builder for simple callbacks.
+     * Builder for simple callbacks.
      *
-     * Modules can add their own callback function to this builder to be executed when
-     * the builder is executed with the same function arguments.
+     * Components can add their own callback function to this builder to be
+     * executed when the service is executed with the same function arguments.
      *
-     * @tparam Size
-     *      Maximum number of callbacks that may be registered.
+     * @tparam NumFuncs
+     *      The number of functions currently registered with this builder.
      *
-     * @tparam Args
+     * @tparam ArgTypes
      *      List of argument types that must be passed into the callback when it is invoked.
+     *
+     * @see cib::callback_meta
      */
-    template<int Size = 0, typename... Args>
+    template<int NumFuncs = 0, typename... ArgTypes>
     struct callback {
     private:
-        using func_ptr_t = void(*)(Args...);
+        using func_ptr_t = void(*)(ArgTypes...);
 
-        std::array<func_ptr_t, Size> funcs;
+        std::array<func_ptr_t, NumFuncs> funcs;
 
+        /**
+         * Runtime implementation of a callback service.
+         *
+         * Calls each registered function in an undefined order. The order
+         * functions are called should not be depended upon and could
+         * change from one release to the next.
+         *
+         * This function will be available from nexus::builder<...> or
+         * cib::built<...>.
+         *
+         * @tparam BuilderValue
+         *      A type that contains a constexpr static value field with the
+         *      fully initialized callback builder.
+         *
+         * @param args
+         *      The arguments to be passed to every registered function.
+         *
+         * @see cib::nexus
+         * @see cib::built
+         */
         template<typename BuilderValue>
-        static void run(Args... args) {
-            CIB_CONSTEXPR auto handlerBuilder = BuilderValue::value;
-            CIB_CONSTEXPR auto numFuncs = std::integral_constant<int, Size>{};
+        static void run(ArgTypes... args) {
+            CIB_CONSTEXPR auto handler_builder = BuilderValue::value;
+            CIB_CONSTEXPR auto num_funcs = std::integral_constant<int, NumFuncs>{};
 
-            detail::for_each(numFuncs, [&](auto i){
-                CIB_CONSTEXPR auto func = handlerBuilder.funcs[i];
+            detail::for_each(num_funcs, [&](auto i){
+                CIB_CONSTEXPR auto func = handler_builder.funcs[i];
                 func(args...);
             });
         }
 
     public:
         CIB_CONSTEVAL callback() = default;
 
-        template<typename PrevFuncsT>
+        template<typename PrevFuncsType>
         CIB_CONSTEVAL callback(
-            PrevFuncsT const & prev_funcs,
+            PrevFuncsType const & prev_funcs,
             func_ptr_t new_func
         )
             : funcs{}
@@ -55,36 +77,67 @@ namespace cib {
                 funcs[i] = prev_funcs[i];
             }
 
-            funcs[Size - 1] = new_func;
+            funcs[NumFuncs - 1] = new_func;
         }
 
-        // cib uses "add(...)" to add features to service builders
-        CIB_CONSTEVAL auto add(func_ptr_t const & func) const {
-            return callback<Size + 1, Args...>{funcs, func};
+        /**
+         * Add a function to be executed when the callback service is invoked.
+         *
+         * Do not call this function directly. The library will add functions
+         * to service builders based on a project's cib::config and cib::extend
+         * declarations.
+         *
+         * @param func
+         *
+         * @return
+         *      A version of this callback builder with the addition of func.
+         *
+         * @see cib::extend
+         * @see cib::nexus
+         */
+        [[nodiscard]] CIB_CONSTEVAL auto add(func_ptr_t const & func) const {
+            return callback<NumFuncs + 1, ArgTypes...>{funcs, func};
         }
 
         /**
-         * Build and return a function pointer to the implemented callback builder. Used
-         * by cib library to automatically build an initialized builder. Do not call.
+         * Build and return a function pointer to the implemented callback
+         * builder. Used by cib nexus to automatically build an initialized
+         * builder.
+         *
+         * Do not call directly.
          *
          * @tparam BuilderValue
          *      Struct that contains a "static constexpr auto value" field with the initialized
          *      builder.
          *
          * @return
-         *      Function pointer to callback builder.
+         *      Function pointer to the implemented callback service.
          */
         template<typename BuilderValue>
         [[nodiscard]] CIB_CONSTEVAL static auto build() {
             return run<BuilderValue>;
         }
     };
 
-    template<typename... Args>
+    /**
+     * Extend this to create named callback services.
+     *
+     * Types that extend callback_meta can be used as unique names with
+     * cib::exports and cib::extend.
+     *
+     * @tparam ArgTypes
+     *      The function arguments that must be passed into the callback
+     *      services implementation. Any function registered with this
+     *      callback service must also have a compatible signature.
+     *
+     * @see cib::exports
+     * @see cib::extend
+     */
+    template<typename... ArgTypes>
     struct callback_meta :
         public cib::builder_meta<
-            callback<0, Args...>,
-            void(*)(Args...)>
+            callback<0, ArgTypes...>,
+            void(*)(ArgTypes...)>
     {};
 }
 

include/cib/cib.hpp

@@ -42,8 +42,6 @@
 #include "nexus.hpp"
 #include "built.hpp"
 #include "config.hpp"
-#include "detail/compiler.hpp"
-#include "detail/meta.hpp"
 #include "builder_meta.hpp"