Start documenting current items

CMakeLists.txt

@@ -41,39 +41,40 @@ endif()
 include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/hyperion_compiler_settings.cmake)
 include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/hyperion_enable_warnings.cmake)
 
-set(HYPERION_PLATFORM_INCLUDE_DIRECTORIES
+set(HYPERION_MPL_INCLUDE_DIRECTORIES
     "${CMAKE_CURRENT_SOURCE_DIR}/include"
 )
-set(HYPERION_PLATFORM_INCLUDE_PATH
+set(HYPERION_MPL_INCLUDE_PATH
     "${CMAKE_CURRENT_SOURCE_DIR}/include/hyperion"
 )
-set(HYPERION_PLATFORM_HEADERS
-    "${HYPERION_PLATFORM_INCLUDE_PATH}/mpl/index.h"
-    "${HYPERION_PLATFORM_INCLUDE_PATH}/mpl/list.h"
-    "${HYPERION_PLATFORM_INCLUDE_PATH}/mpl/value.h"
-    "${HYPERION_PLATFORM_INCLUDE_PATH}/mpl/algorithms.h"
-    "${HYPERION_PLATFORM_INCLUDE_PATH}/mpl/algorithms/all_of.h"
-    "${HYPERION_PLATFORM_INCLUDE_PATH}/mpl/concepts.h"
-    "${HYPERION_PLATFORM_INCLUDE_PATH}/mpl/concepts/comparable.h"
-    "${HYPERION_PLATFORM_INCLUDE_PATH}/mpl/concepts/operator_able.h"
-    "${HYPERION_PLATFORM_INCLUDE_PATH}/mpl/concepts/std_supplemental.h"
-    "${HYPERION_PLATFORM_INCLUDE_PATH}/mpl/type_traits.h"
-    "${HYPERION_PLATFORM_INCLUDE_PATH}/mpl/type_traits/is_comparable.h"
-    "${HYPERION_PLATFORM_INCLUDE_PATH}/mpl/type_traits/is_operator_able.h"
-    "${HYPERION_PLATFORM_INCLUDE_PATH}/mpl/type_traits/std_supplemental.h"
+set(HYPERION_MPL_HEADERS
+    "${HYPERION_MPL_INCLUDE_PATH}/mpl.h"
+    "${HYPERION_MPL_INCLUDE_PATH}/mpl/index.h"
+    "${HYPERION_MPL_INCLUDE_PATH}/mpl/list.h"
+    "${HYPERION_MPL_INCLUDE_PATH}/mpl/value.h"
+    "${HYPERION_MPL_INCLUDE_PATH}/mpl/algorithms.h"
+    "${HYPERION_MPL_INCLUDE_PATH}/mpl/algorithms/all_of.h"
+    "${HYPERION_MPL_INCLUDE_PATH}/mpl/concepts.h"
+    "${HYPERION_MPL_INCLUDE_PATH}/mpl/concepts/comparable.h"
+    "${HYPERION_MPL_INCLUDE_PATH}/mpl/concepts/operator_able.h"
+    "${HYPERION_MPL_INCLUDE_PATH}/mpl/concepts/std_supplemental.h"
+    "${HYPERION_MPL_INCLUDE_PATH}/mpl/type_traits.h"
+    "${HYPERION_MPL_INCLUDE_PATH}/mpl/type_traits/is_comparable.h"
+    "${HYPERION_MPL_INCLUDE_PATH}/mpl/type_traits/is_operator_able.h"
+    "${HYPERION_MPL_INCLUDE_PATH}/mpl/type_traits/std_supplemental.h"
 )
 
 add_library(hyperion_mpl INTERFACE)
 add_library(hyperion::mpl ALIAS hyperion_mpl)
 target_include_directories(
     hyperion_mpl
     INTERFACE
-    ${HYPERION_PLATFORM_INCLUDE_DIRECTORIES}
+    ${HYPERION_MPL_INCLUDE_DIRECTORIES}
 )
 target_sources(
     hyperion_mpl
     INTERFACE
-    ${HYPERION_PLATFORM_HEADERS}
+    ${HYPERION_MPL_HEADERS}
 )
 target_link_libraries(
     hyperion_mpl
@@ -95,20 +96,20 @@ target_link_libraries(hyperion_mpl_main
 hyperion_compile_settings(hyperion_mpl_main)
 hyperion_enable_warnings(hyperion_mpl_main)
 
-set(HYPERION_PLATFORM_DOXYGEN_OUTPUT_DIR "${CMAKE_CURRENT_SOURCE_DIR}/docs/_build/html")
-set(HYPERION_PLATFORM_DOXYGEN_HTML "${HYPERION_PLATFORM_DOXYGEN_OUTPUT_DIR}/index.html")
+set(HYPERION_MPL_DOXYGEN_OUTPUT_DIR "${CMAKE_CURRENT_SOURCE_DIR}/docs/_build/html")
+set(HYPERION_MPL_DOXYGEN_HTML "${HYPERION_MPL_DOXYGEN_OUTPUT_DIR}/index.html")
 
-set(HYPERION_PLATFORM_DOCS_DIR "${CMAKE_CURRENT_SOURCE_DIR}/docs")
-set(HYPERION_PLATFORM_DOCS_FILES
-    "${HYPERION_PLATFORM_DOCS_DIR}/index.rst"
-    "${HYPERION_PLATFORM_DOCS_DIR}/quick_start.rst"
+set(HYPERION_MPL_DOCS_DIR "${CMAKE_CURRENT_SOURCE_DIR}/docs")
+set(HYPERION_MPL_DOCS_FILES
+    "${HYPERION_MPL_DOCS_DIR}/index.rst"
+    "${HYPERION_MPL_DOCS_DIR}/quick_start.rst"
 )
 
 add_custom_command(
-    OUTPUT ${HYPERION_PLATFORM_DOXYGEN_HTML}
-    DEPENDS ${HYPERION_PLATFORM_HEADERS} ${DOCS_FILES}
+    OUTPUT ${HYPERION_MPL_DOXYGEN_HTML}
+    DEPENDS ${HYPERION_MPL_HEADERS} ${DOCS_FILES}
     COMMAND sphix-build -M html . _build
-    WORKING_DIRECTORY ${HYPERION_PLATFORM_DOCS_DIR}
+    WORKING_DIRECTORY ${HYPERION_MPL_DOCS_DIR}
     MAIN_DEPENDENCY
     COMMENT "Generating documentation with doxygen, sphinx, and breathe"
     VERBATIM
@@ -117,6 +118,6 @@ add_custom_command(
 add_custom_target(hyperion_mpl_doxygen DEPENDS ${DOXYGEN_HTML})
 
 include(GNUInstallDirs)
-install(DIRECTORY ${HYPERION_PLATFORM_DOXYGEN_OUTPUT_DIR} DESTINATION ${CMAKE_INSTALL_DOCDIR})
+install(DIRECTORY ${HYPERION_MPL_DOXYGEN_OUTPUT_DIR} DESTINATION ${CMAKE_INSTALL_DOCDIR})
 install(DIRECTORY include/ DESTINATION include)
 install(TARGETS hyperion_mpl DESTINATION lib)

docs/Doxyfile

@@ -44,7 +44,7 @@ PROJECT_NUMBER         =
 # for a project that appears at the top of each page and should give viewer a
 # quick idea about the purpose of the project. Keep the description short.
 
-PROJECT_BRIEF = "Platform and Architecture Detection and Feature Test Macros for C++. Part of Hyperion Engine."
+PROJECT_BRIEF = "C++20 Metaprogramming library inspired by Boost.Hana. Part of Hyperion Engine."
 
 # With the PROJECT_LOGO tag one can specify a logo or an icon that is included
 # in the documentation. The maximum height of the logo should not exceed 55
@@ -2205,8 +2205,7 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             = IGNORE_PADDING_START=""\
-                         IGNORE_PADDING_STOP=""
+PREDEFINED             = HYPERION_PLATFORM_STD_LIB_HAS_COMPARE=1
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The

docs/concepts.rst

@@ -0,0 +1,9 @@
+hyperion::mpl::concepts
+**************************
+
+.. doxygengroup:: concepts
+
+.. toctree::
+    :caption: Comparison Operator Detection
+
+    concepts/comparable

docs/concepts/comparable.rst

@@ -0,0 +1,12 @@
+Comparability Concepts
+**********************
+
+.. doxygengroup:: comparability_concepts
+
+.. doxygenconcept:: hyperion::mpl::concepts::EqualityComparable
+.. doxygenconcept:: hyperion::mpl::concepts::InequalityComparable
+.. doxygenconcept:: hyperion::mpl::concepts::LessThanComparable
+.. doxygenconcept:: hyperion::mpl::concepts::LessThanOrEqualComparable
+.. doxygenconcept:: hyperion::mpl::concepts::GreaterThanComparable
+.. doxygenconcept:: hyperion::mpl::concepts::GreaterThanOrEqualComparable
+.. doxygenconcept:: hyperion::mpl::concepts::ThreeWayComparable

docs/conf.py

@@ -114,5 +114,4 @@
         "hyperion::mpl": "_build/xml"
 }
 breathe_default_project = "hyperion::mpl"
-breathe_default_members = ('members')
 

docs/index.rst

@@ -26,3 +26,12 @@ For an overview of each module, see the links in the left sidebar or below.
 
     genindex
 
+.. toctree::
+    :caption: Type Traits
+
+    type_traits
+
+.. toctree::
+    :caption: Concept Definitions
+
+    concepts

docs/type_traits.rst

@@ -0,0 +1,14 @@
+hyperion::mpl::type_traits
+**************************
+
+.. doxygengroup:: type_traits
+
+.. toctree::
+    :caption: Comparison Operator Detection
+
+    type_traits/is_comparable
+
+.. toctree::
+    :caption: General Operator Detection
+
+    type_traits/is_operator_able

docs/type_traits/is_comparable.rst

@@ -0,0 +1,4 @@
+Comparison Operator Detection
+*****************************
+
+.. doxygengroup:: comparison_operator_detection

docs/type_traits/is_operator_able.rst

@@ -0,0 +1,4 @@
+General Operator Detection
+*****************************
+
+.. doxygengroup:: general_operator_detection

include/hyperion/mpl.h

@@ -0,0 +1,39 @@
+/// @file mpl.h
+/// @author Braxton Salyer <braxtonsalyer@gmail.com>
+/// @brief Catch-all header for the Hyperion meta-programming library
+/// @version 0.1
+/// @date 2024-01-27
+///
+/// MIT License
+/// @copyright Copyright (c) 2024 Braxton Salyer <braxtonsalyer@gmail.com>
+///
+/// Permission is hereby granted, free of charge, to any person obtaining a copy
+/// of this software and associated documentation files (the "Software"), to deal
+/// in the Software without restriction, including without limitation the rights
+/// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+/// copies of the Software, and to permit persons to whom the Software is
+/// furnished to do so, subject to the following conditions:
+///
+/// The above copyright notice and this permission notice shall be included in all
+/// copies or substantial portions of the Software.
+///
+/// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+/// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+/// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+/// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+/// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+/// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+/// SOFTWARE.
+
+#ifndef HYPERION_MPL_H
+#define HYPERION_MPL_H
+
+/// @defgroup mpl Metaprogramming Library
+/// Hyperion's metaprogramming library provides a full-featured set of basic
+/// metaprogramming operations, inspired by Boost.Hana. It uses `constexpr` and value
+/// semantics to make metaprogramming functional, simple, and (mostly) read and write
+/// like normal code for users, instead of needing to rely on complex template-based
+/// techniques that are difficult to reason about.
+/// @headerfile "hyperion/mpl.h"
+
+#endif // HYPERION_MPL_H

include/hyperion/mpl/concepts.h

@@ -28,6 +28,19 @@
 #ifndef HYPERION_MPL_CONCEPTS_H
 #define HYPERION_MPL_CONCEPTS_H
 
+/// @ingroup mpl
+/// @{
+/// @defgroup concepts Concepts
+/// Hyperion provides an assortment of metaprogramming `concept` definitions used to
+/// define various conceptual models and characteristics of types.
+/// Some of these are purely novel, such as comparability, while others are supplemental
+/// to, or less stringent than, those provided by the standard, doing something similar
+/// to existing `concept`s, but filling in gaps in the API surface that were overlooked
+/// or missing for other reasons, or provided an alternative definition that is narrower
+/// in scope.
+/// @headerfile hyperion/mpl/concepts.h
+/// @}
+
 #include <hyperion/mpl/concepts/comparable.h>
 #include <hyperion/mpl/concepts/operator_able.h>
 #include <hyperion/mpl/concepts/std_supplemental.h>

include/hyperion/mpl/concepts/comparable.h

@@ -29,33 +29,91 @@
 #ifndef HYPERION_MPL_CONCEPTS_COMPARABLE_H
 #define HYPERION_MPL_CONCEPTS_COMPARABLE_H
 
-#include <hyperion/mpl/type_traits/is_comparable.h>
+#include <hyperion/platform/def.h>
+
+#if HYPERION_PLATFORM_STD_LIB_HAS_COMPARE
+    #include <compare>
+#endif // HYPERION_PLATFORM_STD_LIB_HAS_COMPARE
+
+/// @ingroup concepts
+/// @{
+/// @defgroup comparability_concepts Comparability Concepts
+/// Assortment of `concept` definitions requiring types to
+/// be comparable in various ways.
+///
+/// # Example:
+/// @code {.cpp}
+/// #include <hyperion/mpl/concepts/comparable.h
+///
+/// using namespace hyperion::mpl::concepts;
+/// struct not_comparable {};
+///
+/// static_assert(EqualityComparable<int, int>);
+/// static_assert(!EqualityComparable<not_comparable, not_comparable>);
+///
+/// @endcode
+/// @headerfile hyperion/mpl/concepts/comparable.h
+/// @}
 
 namespace hyperion::mpl::concepts {
 
+    /// @brief Concept definition requiring that a `TLhs` is
+    /// equality comparable with a `TRhs`
+    /// @ingroup comparability_concepts
+    /// @headerfile hyperion/mpl/concepts/comparable.h
     template<typename TLhs, typename TRhs>
-    concept EqualityComparable = type_traits::is_equality_comparable_v<TLhs, TRhs>;
-
+    concept EqualityComparable = requires(const TLhs& lhs, const TRhs& rhs) {
+        lhs == rhs;
+        rhs == lhs;
+    };
+
+    /// @brief Concept definition requiring that a `TLhs` is
+    /// inequality comparable with a `TRhs`
+    /// @ingroup comparability_concepts
+    /// @headerfile hyperion/mpl/concepts/comparable.h
     template<typename TLhs, typename TRhs>
-    concept InequalityComparable = type_traits::is_inequality_comparable_v<TLhs, TRhs>;
-
+    concept InequalityComparable = requires(const TLhs& lhs, const TRhs& rhs) {
+        lhs != rhs;
+        rhs != lhs;
+    };
+
+    /// @brief Concept definition requiring that a `TLhs` is
+    /// less-than comparable with a `TRhs`
+    /// @ingroup comparability_concepts
+    /// @headerfile hyperion/mpl/concepts/comparable.h
     template<typename TLhs, typename TRhs>
-    concept LessThanComparable = type_traits::is_less_than_comparable_v<TLhs, TRhs>;
+    concept LessThanComparable = requires(const TLhs& lhs, const TRhs& rhs) { lhs < rhs; };
 
+    /// @brief Concept definition requiring that a `TLhs` is
+    /// less-than-or-equal comparable with a `TRhs`
+    /// @ingroup comparability_concepts
+    /// @headerfile hyperion/mpl/concepts/comparable.h
     template<typename TLhs, typename TRhs>
-    concept LessThanOrEqualComparable = type_traits::is_less_than_or_equal_comparable_v<TLhs, TRhs>;
+    concept LessThanOrEqualComparable = requires(const TLhs& lhs, const TRhs& rhs) { lhs <= rhs; };
 
+    /// @brief Concept definition requiring that a `TLhs` is
+    /// greater-than comparable with a `TRhs`
+    /// @ingroup comparability_concepts
+    /// @headerfile hyperion/mpl/concepts/comparable.h
     template<typename TLhs, typename TRhs>
-    concept GreaterThanComparable = type_traits::is_greater_than_comparable_v<TLhs, TRhs>;
+    concept GreaterThanComparable = requires(const TLhs& lhs, const TRhs& rhs) { lhs > rhs; };
 
+    /// @brief Concept definition requiring that a `TLhs` is
+    /// greater-than-or-equal comparable with a `TRhs`
+    /// @ingroup comparability_concepts
+    /// @headerfile hyperion/mpl/concepts/comparable.h
     template<typename TLhs, typename TRhs>
     concept GreaterThanOrEqualComparable
-        = type_traits::is_greater_than_or_equal_comparable_v<TLhs, TRhs>;
+        = requires(const TLhs& lhs, const TRhs& rhs) { lhs >= rhs; };
 
 #if HYPERION_PLATFORM_STD_LIB_HAS_COMPARE
 
+    /// @brief Concept definition requiring that a `TLhs` is
+    /// three-way comparable with a `TRhs`
+    /// @ingroup comparability_concepts
+    /// @headerfile hyperion/mpl/concepts/comparable.h
     template<typename TLhs, typename TRhs>
-    concept ThreeWayComparable = type_traits::is_three_way_comparable_v<TLhs, TRhs>;
+    concept ThreeWayComparable = std::three_way_comparable_with<TLhs, TRhs>;
 
 #endif // HYPERION_PLATFORM_STD_LIB_HAS_COMPARE
 
@@ -115,7 +173,8 @@ namespace hyperion::mpl::concepts {
                       "hyperion::mpl::concepts::ThreeWayComparable test case 3 failing");
 
 #endif // HYPERION_PLATFORM_STD_LIB_HAS_COMPARE
-    }  // namespace _test
+
+    } // namespace _test
 } // namespace hyperion::mpl::concepts
 
 #endif // HYPERION_MPL_CONCEPTS_IS_COMPARABLE_H