added documentation to the utils header, moved utils into a subdirectory

Author: mgerhold

CMakeLists.txt

@@ -57,8 +57,8 @@ add_executable(oopetris
         src/random.hpp
         src/recording.hpp
         src/input_event.hpp
-        src/utils.hpp
-        src/utils.cpp
+        src/utils/utils.hpp
+        src/utils/utils.cpp
         src/command_line_arguments.hpp
         src/controls.hpp
         src/mino_stack.cpp

src/meson.build

@@ -52,3 +52,5 @@ src_files += files(
 )
 
 inc_dirs += include_directories('.')
+
+subdir('utils')

src/recording.hpp

@@ -5,7 +5,7 @@
 #include "tetrion.hpp"
 #include "tetrion_snapshot.hpp"
 #include "types.hpp"
-#include "utils.hpp"
+#include "utils/utils.hpp"
 #include <filesystem>
 #include <fstream>
 #include <spdlog/spdlog.h>

src/utils/meson.build

@@ -0,0 +1,6 @@
+src_files += files(
+    'utils.hpp',
+    'utils.cpp',
+)
+
+inc_dirs += include_directories('.')

src/utils.cpp renamed to src/utils/utils.cpp

@@ -1,7 +1,7 @@
 #include "utils.hpp"
+#include "spdlog/spdlog.h"
 #include <chrono>
 #include <ctime>
-#include <spdlog/spdlog.h>
 
 namespace utils {
     [[nodiscard]] std::string current_date_time_iso8601() {

src/utils.hpp renamed to src/utils/utils.hpp

@@ -15,8 +15,20 @@ namespace utils {
     template<class T>
     concept integral = std::is_integral_v<T>;
 
+    /**
+     * @brief Returns the current date and time as a string in ISO 8601 format without using any separators except for
+     * 'T' between the date and the time.
+     * @return The current date and time string.
+     */
     [[nodiscard]] std::string current_date_time_iso8601();
 
+    /**
+     * @brief Converts between big endian and little endian. This function is needed since not all compilers support
+     * std::byteswap as of yet.
+     * @tparam Integral The type of the value to convert.
+     * @param value The value to convert.
+     * @return The converted value.
+     */
     template<integral Integral>
     [[nodiscard]] constexpr Integral byte_swap(Integral value) noexcept {
         // based on source: slartibartswift
@@ -29,6 +41,12 @@ namespace utils {
         return result;
     }
 
+    /**
+     * @brief Converts from the machine's native byte order to little endian. On a little endian machine, this function
+     * does return the input value.
+     * @param value A value in the machine's native byte order.
+     * @return The value in little endian.
+     */
     [[nodiscard]] constexpr auto to_little_endian(integral auto value) {
         if constexpr (std::endian::native == std::endian::little) {
             return value;
@@ -37,6 +55,12 @@ namespace utils {
         }
     }
 
+    /**
+     * @brief Converts from little endian to the machine's native byte order. On a little endian machine, this function
+     * does return the input value.
+     * @param value A value in little endian.
+     * @return The value in the machine's native byte order.
+     */
     [[nodiscard]] constexpr auto from_little_endian(integral auto value) {
         return to_little_endian(value);
     }