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/meson.build

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

src/recording.hpp

@@ -3,7 +3,7 @@
 #include "input_event.hpp"
 #include "random.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

@@ -9,8 +9,20 @@
 #include <string>
 
 namespace utils {
+    /**
+     * @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<std::integral Integral>
     [[nodiscard]] constexpr inline Integral byte_swap(Integral value) noexcept {
         // source: https://en.cppreference.com/w/cpp/numeric/byteswap
@@ -20,6 +32,12 @@ namespace utils {
         return std::bit_cast<Integral>(value_representation);
     }
 
+    /**
+     * @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 inline auto to_little_endian(std::integral auto value) {
         if constexpr (std::endian::native == std::endian::little) {
             return value;
@@ -28,6 +46,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 inline auto from_little_endian(std::integral auto value) {
         return to_little_endian(value);
     }