Add comprehensive documentation to SlickQueue class

- Added Doxygen-style comments for class overview, constructors, and all public methods
- Enhanced API documentation for better usability and maintainability of the lock-free queue implementation
- Minor fix: corrected size() method to return size_ instead of mask_ + 1 for accuracy

Author: kzhdev

include/slick_queue/slick_queue.h

@@ -35,6 +35,14 @@
 
 namespace slick {
 
+/**
+ * @brief A lock-free multi-producer multi-consumer queue with optional shared memory support.
+ * 
+ * This queue allows a multiple producer thread to write data and a multiple consumer thread to read data concurrently without locks.
+ * It can optionally use shared memory for inter-process communication.
+ * 
+ * @tparam T The type of elements stored in the queue.
+ */
 template<typename T>
 class SlickQueue {
     struct slot {
@@ -61,6 +69,15 @@ class SlickQueue {
 #endif
 
 public:
+    /**
+     * @brief Construct a new SlickQueue object
+     * 
+     * @param size The size of the queue, must be a power of 2.
+     * @param shm_name The name of the shared memory segment. If nullptr, the queue will use local memory.
+     * 
+     * @throws std::runtime_error if shared memory allocation fails.
+     * @throws std::invalid_argument if size is not a power of 2.
+     */
     SlickQueue(uint32_t size, const char* const shm_name = nullptr)
         : size_(size)
         , buffered_size_(size + 1024)   // add some buffer at the end
@@ -75,13 +92,15 @@ class SlickQueue {
         if (shm_name) {
             allocate_shm_data(shm_name, false);
         }
-
-        // if (own_) {
-        //     // invalidate first slot
-        //     control_[0].data_index.store(-1, std::memory_order_relaxed);
-        // }
     }
 
+    /**
+     * @brief Open an existing SlickQueue in shared memory
+     * 
+     * @param shm_name The name of the shared memory segment.
+     * 
+     * @throws std::runtime_error if shared memory allocation fails or the segment does not exist.
+     */
     SlickQueue(const char* const shm_name)
         : own_(false)
         , use_shm_(true)
@@ -124,32 +143,75 @@ class SlickQueue {
         }
     }
 
+    /**
+     * @brief Check if the queue owns the memory buffer
+     * @return true if the queue owns the memory buffer, false otherwise
+     */
     bool own_buffer() const noexcept { return own_; }
+
+    /**
+     * @brief Check if the queue uses shared memory
+     * @return true if the queue uses shared memory, false otherwise
+     */
     bool use_shm() const noexcept { return use_shm_; }
-    constexpr uint32_t size() const noexcept { return mask_ + 1; }
 
+    /**
+     * @brief Get the size of the queue
+     * @return Size of the queue
+     */
+    constexpr uint32_t size() const noexcept { return size_; }
+
+    /**
+     * @brief Get the initial reading index, which is 0 if the queue is newly created or the current writing index if opened existing 
+     * @return Initial reading index
+     */
     uint64_t initial_reading_index() const noexcept {
         return reserved_->load(std::memory_order_relaxed);
     }
 
+    /**
+     * @brief Reserve space in the queue for writing
+     * @param n Number of slots to reserve, default is 1
+     * @return The starting index of the reserved space
+     */
     uint64_t reserve(uint32_t n = 1) noexcept {
         return reserved_->fetch_add(n, std::memory_order_acq_rel);
     }
 
+    /**
+     * @brief Access the reserved space for writing
+     * @param index The index returned by reserve()
+     * @return Pointer to the reserved space
+     */
     T* operator[] (uint64_t index) noexcept {
         return &data_[index & mask_];
     }
 
+    /**
+     * @brief Access the reserved space for writing (const version)
+     * @param index The index returned by reserve()
+     * @return Pointer to the reserved space
+     */
     const T* operator[] (uint64_t index) const noexcept {
         return &data_[index & mask_];
     }
 
+    /**
+     * @brief Publish the data written in the reserved space
+     * @param index The index returned by reserve()
+     * @param n Number of slots to publish, default is 1
+     */
     void publish(uint64_t index, uint32_t n = 1) noexcept {
         auto& slot = control_[index & mask_];
         slot.size = n;
         slot.data_index.store(index, std::memory_order_release);
     }
 
+    /**
+     * @brief Read data from the queue
+     * @param read_index Reference to the reading index, will be updated to the next index after reading
+     * @return Pair of pointer to the data and the size of the data, or nullptr and 0 if no data is available
+     */
     std::pair<T*, uint32_t> read(uint64_t& read_index) noexcept {
         auto& slot = control_[read_index & mask_];
         auto index = slot.data_index.load(std::memory_order_relaxed);
@@ -169,7 +231,8 @@ class SlickQueue {
     }
 
     /**
-    * Read the last published data in the queue
+    * @brief Read the last published data in the queue
+    * @return Pointer to the last published data, or nullptr if no data is available
     */
     T* read_last() noexcept {
         auto reserved = reserved_->load(std::memory_order_relaxed);
@@ -192,6 +255,11 @@ class SlickQueue {
         return &data_[index & mask_];
     }
 
+    /**
+     * @brief Reset the queue, invalidating all existing data
+     * 
+     * Note: This function is not thread-safe and should be called when no other threads are accessing the queue.
+     */
     void reset() noexcept {
         if (use_shm_) {
             control_ = new ((uint8_t*)lpvMem_ + 64) slot[buffered_size_];