docs(core): cleanup memory docs

core/include/cubos/core/memory/buffer_stream.hpp

@@ -1,32 +1,47 @@
+/// @file
+/// @brief Class @ref cubos::core::memory::BufferStream.
+/// @ingroup core-memory
+
 #pragma once
 
 #include <cubos/core/memory/stream.hpp>
 
 namespace cubos::core::memory
 {
-    /// Implements a stream that writes to/reads from a buffer.
+    /// @brief Stream implementation which writes to/reads from a buffer.
+    /// @ingroup core-memory
     class BufferStream : public Stream
     {
     public:
-        /// @param buffer The buffer to read/write from.
-        /// @param size The size of the buffer.
+        ~BufferStream() override;
+
+        /// @brief Constructs using an existing buffer.
+        /// @param buffer Buffer to read/write from.
+        /// @param size Size of the buffer.
+        /// @param readOnly Whether the buffer is read-only.
         BufferStream(void* buffer, std::size_t size, bool readOnly = false);
 
-        /// @param buffer The buffer to read/write from.
-        /// @param size The size of the buffer.
+        /// @brief Constructs using a read-only buffer.
+        /// @param buffer Buffer to read/write from.
+        /// @param size Size of the buffer.
         BufferStream(const void* buffer, std::size_t size);
 
-        /// Initializes a buffer stream with a new buffer, initially of the given size.
-        /// When initialized this way, the buffer stream will own the buffer and will delete it when it is destroyed.
-        /// It will expand the buffer when needed.
-        /// @param size The size of the buffer.
+        /// @brief Constructs using a new buffer, managed internally and which grows as needed.
+        /// @param size Initial size of the buffer.
         BufferStream(std::size_t size = 16);
 
-        ~BufferStream() override;
-        BufferStream(const BufferStream& /*other*/);
-        BufferStream(BufferStream&& /*other*/) noexcept;
+        /// @brief Constructs a copy of another buffer stream. If the given buffer stream owns its
+        /// buffer, the copy will also create its own buffer. Otherwise, it will share the buffer
+        /// with the original.
+        /// @param other Buffer stream to copy.
+        BufferStream(const BufferStream& other);
+
+        /// @brief Move constructs.
+        /// @param other Buffer stream to move.
+        BufferStream(BufferStream&& other) noexcept;
 
-        /// Gets the buffer of this stream.
+        /// @brief Gets the buffer of this stream.
+        /// @return Buffer.
         const void* getBuffer() const;
 
         // Method implementations.

core/include/cubos/core/memory/endianness.hpp

@@ -1,43 +1,53 @@
+/// @file
+/// @brief Endianness utility functions.
+/// @ingroup core-memory
+
 #pragma once
 
 namespace cubos::core::memory
 {
-    /// Swaps the bytes of a value, changing the endianness.
-    /// @tparam T The type of the value.
-    /// @param value The value to swap.
-    /// @return The swapped value.
+    /// @brief Swaps the bytes of a value, changing its endianness.
+    /// @tparam T Value type.
+    /// @param value Value to swap.
+    /// @return Swapped value.
+    /// @ingroup core-memory
     template <typename T>
     T swapBytes(T value);
 
-    /// Checks if the current platform is little endian.
-    /// @return True if the current platform is little endian, false otherwise.
+    /// @brief Checks if the current platform is little endian.
+    /// @return Whether its little endian.
+    /// @ingroup core-memory
     bool isLittleEndian();
 
-    /// Converts a value from little endianness to local endianness.
-    /// @tparam T The type of the value.
-    /// @param value The value to convert.
-    /// @return The converted value.
+    /// @brief Converts a value from little endianness to local endianness.
+    /// @tparam T Value type.
+    /// @param value Value to convert.
+    /// @return Converted value.
+    /// @ingroup core-memory
     template <typename T>
     T fromLittleEndian(T value);
 
-    /// Converts a value from local endianness to little endianness.
-    /// @tparam T The type of the value.
-    /// @param value The value to convert.
-    /// @return The converted value.
+    /// @brief Converts a value from local endianness to little endianness.
+    /// @tparam T Value type.
+    /// @param value Value to convert.
+    /// @return Converted value.
+    /// @ingroup core-memory
     template <typename T>
     T toLittleEndian(T value);
 
-    /// Converts a value from big endianness to local endianness.
-    /// @tparam T The type of the value.
-    /// @param value The value to convert.
-    /// @return The converted value.
+    /// @brief Converts a value from big endianness to local endianness.
+    /// @tparam T Value type.
+    /// @param value Value to convert.
+    /// @return Converted value.
+    /// @ingroup core-memory
     template <typename T>
     T fromBigEndian(T value);
 
-    /// Converts a value from local endianness to big endianness.
-    /// @tparam T The type of the value.
-    /// @param value The value to convert.
-    /// @return The converted value.
+    /// @brief Converts a value from local endianness to big endianness.
+    /// @tparam T Value type.
+    /// @param value Value to convert.
+    /// @return Converted value.
+    /// @ingroup core-memory
     template <typename T>
     T toBigEndian(T value);
 

core/include/cubos/core/memory/guards.hpp

@@ -1,49 +1,62 @@
+/// @file
+/// @brief Classes @ref cubos::core::memory::ReadGuard and @ref cubos::core::memory::WriteGuard.
+/// @ingroup core-memory
+
 #pragma once
 
 namespace cubos::core::memory
 {
-    /// Utility class to provide safe read-only access to an object using a lock.
+    /// @brief Provides safe read-only access to an object using a lock.
     ///
-    /// @details This class was created because there are multiple parts of the code that need to provide
+    /// This class was created because there are multiple parts of the code that need to provide
     /// access to objects in a thread-safe manner.
     ///
-    /// Usage example:
+    /// ## Usage example
+    ///
+    /// @code{.cpp}
     ///     using AssetMetaRead = core::memory::ReadGuard<AssetMeta, std::shared_lock<std::shared_mutex>>;
+    /// @endcode
     ///
-    /// @tparam T The type of the object to guard.
-    /// @tparam Lock The type of the lock to use.
+    /// @tparam T Guarded object type.
+    /// @tparam Lock Held lock type.
+    /// @ingroup core-memory
     template <typename T, typename Lock>
     class ReadGuard
     {
     public:
-        /// @param object The object to guard.
-        /// @param lock The lock to use.
+        /// @brief Constructor.
+        /// @param object Object to guard.
+        /// @param lock Lock to hold.
         inline ReadGuard(const T& object, Lock&& lock)
             : mObject(object)
             , mLock(std::move(lock))
         {
         }
 
-        /// @param other The other guard to move from.
+        /// @brief Move constructor.
+        /// @param other Guard to move from.
         inline ReadGuard(ReadGuard&& other) noexcept
             : mObject(other.object)
             , mLock(std::move(other.lock))
         {
         }
 
-        /// @returns The underlying object.
+        /// @brief Gets a reference to the underlying object.
+        /// @return Underlying object.
         inline const T& get() const
         {
             return mObject;
         }
 
-        /// @returns The underlying object.
+        /// @brief Gets a reference to the underlying object.
+        /// @return Underlying object.
         inline const T& operator*() const
         {
             return mObject;
         }
 
-        /// @returns The underlying object.
+        /// @brief Gets a pointer to the underlying object.
+        /// @return Underlying object.
         inline const T* operator->() const
         {
             return &mObject;
@@ -54,66 +67,78 @@ namespace cubos::core::memory
         Lock mLock;       ///< Lock used to guard the object.
     };
 
-    /// Utility class to provide safe read-write access to an object using a lock.
+    /// @brief Provides safe read-write access to an object using a lock.
     ///
-    /// @details This class was created because there are multiple parts of the code that need to provide
+    /// This class was created because there are multiple parts of the code that need to provide
     /// access to objects in a thread-safe manner.
     ///
-    /// Usage example:
+    /// ## Usage example
+    ///
+    /// @code{.cpp}
     ///     using AssetMetaWrite = core::memory::WriteGuard<AssetMeta, std::unique_lock<std::shared_mutex>>;
+    /// @endcode
     ///
-    /// @tparam T The type of the object to guard.
-    /// @tparam Lock The type of the lock to use.
+    /// @tparam T Guarded object type.
+    /// @tparam Lock Held lock type.
+    /// @ingroup core-memory
     template <typename T, typename Lock>
     class WriteGuard
     {
     public:
-        /// @param object The object to guard.
-        /// @param lock The lock to use.
+        /// @brief Constructor.
+        /// @param object Object to guard.
+        /// @param lock Lock to hold.
         inline WriteGuard(T& object, Lock&& lock)
             : mObject(object)
             , mLock(std::move(lock))
         {
         }
 
-        /// @param other The other guard to move from.
+        /// @brief Move constructs.
+        /// @param other Guard to move from.
         inline WriteGuard(WriteGuard&& other) noexcept
             : mObject(other.object)
             , mLock(std::move(other.lock))
         {
         }
 
-        /// @returns The underlying object.
+        /// @brief Gets a reference to the underlying object.
+        /// @return Underlying object.
         inline T& get()
         {
             return mObject;
         }
 
-        /// @returns The underlying object.
+        /// @brief Gets a reference to the underlying object.
+        /// @return Underlying object.
         inline T& operator*()
         {
             return mObject;
         }
 
-        /// @returns The underlying object.
+        /// @brief Gets a pointer to the underlying object.
+        /// @return Underlying object.
         inline T* operator->()
         {
             return &mObject;
         }
 
-        /// @returns The underlying object.
+        /// @brief Gets a reference to the underlying object.
+        /// @return Underlying object.
         inline const T& get() const
         {
             return mObject;
         }
 
-        /// @returns The underlying object.
+        /// @brief Gets a reference to the underlying object.
+        /// @return Underlying object.
         inline const T& operator*() const
         {
             return mObject;
         }
 
-        /// @returns The underlying object.
+        /// @brief Gets a pointer to the underlying object.
+        /// @return Underlying object.
         inline const T* operator->() const
         {
             return &mObject;

core/include/cubos/core/memory/module.dox

@@ -0,0 +1,15 @@
+/// @dir
+/// @brief @ref core-memory module.
+
+#pragma once
+
+/// @namespace cubos::core::memory
+/// @brief @ref core-memory module.
+/// @ingroup core-memory
+
+namespace cubos::core::memory
+{
+    /// @defgroup core-memory Memory
+    /// @ingroup core
+    /// @brief Provides memory utilities.
+} // namespace cubos::core::memory

core/include/cubos/core/memory/standard_stream.hpp

@@ -1,3 +1,7 @@
+/// @file
+/// @brief Class @ref cubos::core::memory::StandardStream.
+/// @ingroup core-memory
+
 #pragma once
 
 #include <cstdio>
@@ -6,15 +10,21 @@
 
 namespace cubos::core::memory
 {
-    /// Stream implementation for stdio.
+    /// @brief Stream implementation which wraps a `libc` file pointer.
+    /// @ingroup core-memory
     class StandardStream : public Stream
     {
     public:
-        /// @param file Stdio file to read/write from.
+        ~StandardStream() override;
+
+        /// @brief Constructs.
+        /// @param file File to read/write from.
         /// @param close Should the file be closed when this stream is destructed?
         StandardStream(FILE* file, bool close = false);
-        StandardStream(StandardStream&& /*other*/) noexcept;
-        ~StandardStream() override;
+
+        /// @brief Move constructs.
+        /// @param other Moved stream.
+        StandardStream(StandardStream&& other) noexcept;
 
         std::size_t read(void* data, std::size_t size) override;
         std::size_t write(const void* data, std::size_t size) override;
@@ -24,7 +34,7 @@ namespace cubos::core::memory
         char peek() const override;
 
     private:
-        FILE* mFile; ///< Stdio file to read/write from.
+        FILE* mFile; ///< File to read/write from.
         bool mClose; ///< Should the file be closed when this stream is destructed?
     };
 } // namespace cubos::core::memory