Improve doc

Author: andreiavrammsd

include/msd/blocking_iterator.hpp

@@ -9,9 +9,9 @@
 namespace msd {
 
 /**
- * @brief An iterator that block the current thread, waiting to fetch elements from the channel.
+ * @brief An iterator that blocks the current thread, waiting to fetch elements from the channel.
  *
- * Used to implement channel range-based for loop.
+ * @details Used to implement channel range-based for loop.
  *
  * @tparam Channel Type of channel being iterated.
  */
@@ -80,7 +80,6 @@ class blocking_iterator {
      * @brief Makes iteration continue until the channel is closed and empty.
      *
      * @param other Another blocking_iterator to compare with.
-     *
      * @return true if the channel is not closed or not empty (continue iterating).
      * @return false if the channel is closed and empty (stop iterating).
      */
@@ -95,7 +94,7 @@ class blocking_iterator {
 /**
  * @brief An output iterator pushes elements into a channel. Blocking until the channel is not full.
  *
- * Used to integrate with standard algorithms that require an output iterator.
+ * @details Used to integrate with standard algorithms that require an output iterator.
  *
  * @tparam Channel Type of channel being iterated.
  */
@@ -137,11 +136,9 @@ class blocking_writer_iterator {
     /**
      * @brief Writes an element into the channel, blocking until space is available.
      *
-     * @note There is no effect if the channel is closed.
-     *
      * @param value The value to be written into the channel.
-     *
      * @return The iterator itself.
+     * @note There is no effect if the channel is closed.
      */
     blocking_writer_iterator& operator=(reference value)
     {
@@ -152,12 +149,12 @@ class blocking_writer_iterator {
     /**
      * @brief Not applicable (handled by operator=).
      *
+     * @return The iterator itself.
+     *
      * @note It's uncommon to return a reference to an iterator, but I don't want to return a value from the channel.
      * This iterator is supposed to be used only to write values.
      * I don't know if it's a terrible idea or not, but it looks related to the issue with MSVC
      * in the Transform test in tests/channel_test.cpp.
-     *
-     * @return The iterator itself.
      */
     blocking_writer_iterator& operator*() { return *this; }
 
@@ -183,9 +180,7 @@ class blocking_writer_iterator {
  * @brief Creates a blocking iterator for the given channel.
  *
  * @tparam Channel Type of channel being iterated.
- *
  * @param chan Reference to the channel this iterator will iterate over.
- *
  * @return A blocking iterator for the specified channel.
  */
 template <typename Channel>

include/msd/channel.hpp

@@ -31,7 +31,8 @@ class closed_channel : public std::runtime_error {
 /**
  * @brief Thread-safe container for sharing data between threads.
  *
- * Implements a blocking input iterator.
+ * - Not movable, not copyable.
+ * - Includes a blocking input iterator.
  *
  * @tparam T The type of the elements.
  */
@@ -85,9 +86,7 @@ class channel {
      * @brief Pushes an element into the channel.
      *
      * @tparam Type The type of the elements.
-     *
      * @param value The element to be pushed into the channel.
-     *
      * @return true If an element was successfully pushed into the channel.
      * @return false If the channel is closed.
      */
@@ -114,7 +113,6 @@ class channel {
      * @brief Pops an element from the channel.
      *
      * @param out Reference to the variable where the popped element will be stored.
-     *
      * @return true If an element was successfully read from the channel.
      * @return false If the channel is closed and empty.
      */
@@ -210,9 +208,6 @@ class channel {
      */
     iterator end() noexcept { return blocking_iterator<channel<T>>{*this, true}; }
 
-    /**
-     * Channel cannot be copied or moved.
-     */
     channel(const channel&) = delete;
     channel& operator=(const channel&) = delete;
     channel(channel&&) = delete;

include/msd/static_channel.hpp

@@ -16,9 +16,10 @@ namespace msd {
 /**
  * @brief Thread-safe container for sharing data between threads.
  *
- * Allocates elements on the stack.
- * Does not throw exceptions.
- * Implements a blocking input iterator.
+ * - Allocates elements on the stack.
+ * - Does not throw exceptions.
+ * - Not movable, not copyable.
+ * - Includes a blocking input iterator.
  *
  * @tparam T The type of the elements.
  * @tparam Capacity The maximum number of elements the channel can hold before blocking.
@@ -52,9 +53,7 @@ class static_channel {
      * @brief Pushes an element into the channel.
      *
      * @tparam Type The type of the elements.
-     *
      * @param value The element to be pushed into the channel.
-     *
      * @return true If an element was successfully pushed into the channel.
      * @return false If the channel is closed.
      */
@@ -82,7 +81,6 @@ class static_channel {
      * @brief Pops an element from the channel.
      *
      * @param out Reference to the variable where the popped element will be stored.
-     *
      * @return true If an element was successfully read from the channel.
      * @return false If the channel is closed and empty.
      */
@@ -179,9 +177,6 @@ class static_channel {
      */
     iterator end() noexcept { return blocking_iterator<static_channel<T, Capacity>>{*this, true}; }
 
-    /**
-     * Channel cannot be copied or moved.
-     */
     static_channel(const static_channel&) = delete;
     static_channel& operator=(const static_channel&) = delete;
     static_channel(static_channel&&) = delete;