Docs: Change comment styles

include/config.h

@@ -45,7 +45,7 @@ namespace cfg {
  * The default implementation is using @p static_cast.
  *
  * @tparam From The original type.
- * @tparam To   A new type.
+ * @tparam To A new type.
  *
  * @note
  * If a custom type needs to be saved to a configuration file,
@@ -282,9 +282,7 @@ class VarConverter<std::unordered_map<std::string, T>, std::string> {
     }
 };
 
-/**
- * Basic information about a configuration variable.
- */
+//! Basic information about a configuration variable.
 class VarBase {
 public:
     using Ptr = std::shared_ptr<VarBase>;
@@ -314,9 +312,9 @@ class VarBase {
 /**
  * @brief The configuration variable.
  *
- * @tparam T        The variable type.
- * @tparam FromStr  A converter that can convert a string into a type-matching value.
- * @tparam ToStr    A converter that can convert a type-matching value into a string.
+ * @tparam T The variable type.
+ * @tparam FromStr A converter that can convert a string into a type-matching value.
+ * @tparam ToStr A converter that can convert a type-matching value into a string.
  */
 template <typename T, typename FromStr = VarConverter<std::string, T>,
           typename ToStr = VarConverter<T, std::string>>
@@ -329,8 +327,8 @@ class Var : public VarBase {
     /**
      * @brief The listener for value change events.
      *
-     * @param old_val   The old value before changing.
-     * @param new_val   The new value after changing.
+     * @param old_val The old value before changing.
+     * @param new_val The new value after changing.
      */
     using OnChange = std::function<void(const T& old_val, const T& new_val)>;
 
@@ -387,7 +385,7 @@ class Var : public VarBase {
     /**
      * @brief Remove a listener.
      *
-     * @param key   A unique key corresponding to the listener.
+     * @param key A unique key corresponding to the listener.
      */
     void RemoveListener(const std::uint64_t key) noexcept {
         const std::unique_lock locker {mtx_};
@@ -397,7 +395,7 @@ class Var : public VarBase {
     /**
      * @brief Add a listener for value change events.
      *
-     * @param listener  A listener.
+     * @param listener A listener.
      * @return A unique key corresponding to the listener.
      */
     std::uint64_t AddListener(OnChange listener) noexcept {
@@ -420,9 +418,7 @@ class Var : public VarBase {
     std::unordered_map<std::uint64_t, OnChange> listeners_;
 };
 
-/**
- * The configuration.
- */
+//! The configuration.
 class Config {
 public:
     using Ptr = std::shared_ptr<Config>;
@@ -458,8 +454,8 @@ class Config {
     /**
      * @brief Lookup a variable by its name.
      *
-     * @tparam T    A variable type.
-     * @param name  A variable name.
+     * @tparam T A variable type.
+     * @param name A variable name.
      * @return The found variable or @p nullptr.
      *
      * @exception std::invalid_argument The type of the found variable does not match @p T.

include/containers/block_deque.h

@@ -24,9 +24,7 @@
 
 namespace ws {
 
-/**
- * The block double-ended queue.
- */
+//! The block double-ended queue.
 template <typename T>
 class BlockDeque {
 public:

include/containers/buffer.h

@@ -42,13 +42,16 @@ enum class NewLine {
  * @brief An auto-expandable buffer, supporting storing bytes and strings.
  *
  * @details
+ * @code
  *                 Writing Offset ──────┐
  * Reading Offset ─────┐                │
  *                     │                │
  *                     │                │
  * ┌───────────────────▼────────────────▼────────────────┐
  * │ Prependable Bytes │ Readable Bytes │ Writable Bytes │
  * └───────────────────┴────────────────┴────────────────┘
+ * @endcode
+ *
  * Prependable space can be reused.
  */
 class Buffer {
@@ -163,9 +166,7 @@ class Buffer {
     std::atomic<std::size_t> write_pos_ {0};
 };
 
-/**
- * An enhanced buffer supporting I/O reading and writing.
- */
+//! An enhanced buffer supporting I/O reading and writing.
 class IOBuffer : public Buffer {
 public:
     using Buffer::Buffer;

include/containers/epoller.h

@@ -24,7 +24,10 @@
 namespace ws {
 
 /**
+ * @brief
  * The I/O event notification facility.
+ *
+ * @details
  * It monitors multiple file descriptors to see if I/O is possible on any of them.
  */
 class Epoller {
@@ -34,7 +37,7 @@ class Epoller {
     /**
      * @brief Create an epoller.
      *
-     * @param capacity  The maximum number of file descriptors to be monitored.
+     * @param capacity The maximum number of file descriptors to be monitored.
      *
      * @exception std::system_error Creation failed.
      */
@@ -65,7 +68,7 @@ class Epoller {
     /**
      * @brief Wait for events.
      *
-     * @param time_out  The maximum time to wait.
+     * @param time_out The maximum time to wait.
      * @return
      * The number of file descriptors ready for the requested I/O,
      * or zero if getting a time-out.
@@ -94,8 +97,8 @@ class Epoller {
     /**
      * @brief Perform control operations on a file descriptor.
      *
-     * @param ctl   Addition, deletion or modification.
-     * @param fd    A file descriptor.
+     * @param ctl Addition, deletion or modification.
+     * @param fd A file descriptor.
      * @param events
      * The event associated with the file descriptor.
      * It can be @p std::nullopt if the operation is deletion.

include/containers/heap_timer.h

@@ -32,10 +32,12 @@ namespace ws {
 /**
  * @brief
  * The timer system based on a min-heap.
+ *
+ * @details
  * Timers are maintained in a min-heap ordered by expiration time.
  * When a timer expires, its callback will be invoked.
  *
- * @tparam Key  The type of node keys.
+ * @tparam Key The type of node keys.
  */
 template <typename Key>
 class HeapTimer {
@@ -63,8 +65,8 @@ class HeapTimer {
     /**
      * @brief Adjust a node's expiration time.
      *
-     * @param key           A key.
-     * @param expiration    A new duration from now to its expiration time.
+     * @param key A key.
+     * @param expiration A new duration from now to its expiration time.
      *
      * @exception std::out_of_range The timer system does not contain any node with the specific key.
      */
@@ -73,8 +75,8 @@ class HeapTimer {
     /**
      * @brief Adjust a node's expiration time.
      *
-     * @param key           A key.
-     * @param expiration    A new expiration time.
+     * @param key A key.
+     * @param expiration A new expiration time.
      *
      * @exception std::out_of_range The timer system does not contain any node with the specific key.
      */
@@ -83,19 +85,19 @@ class HeapTimer {
     /**
      * @brief Push a node into the timer system.
      *
-     * @param key           A key.
-     * @param expiration    A duration from now to its expiration time.
-     * @param callback      A time-out callback that will be invoked when the node expires.
+     * @param key A key.
+     * @param expiration A duration from now to its expiration time.
+     * @param callback A time-out callback that will be invoked when the node expires.
      */
     void Push(const Key& key, Clock::duration expiration,
               TimeOutCallback callback) noexcept;
 
     /**
      * @brief Push a node into the timer system.
      *
-     * @param key           A key.
-     * @param expiration    An expiration time.
-     * @param callback      A time-out callback that will be invoked when the node expires.
+     * @param key A key.
+     * @param expiration An expiration time.
+     * @param callback A time-out callback that will be invoked when the node expires.
      */
     void Push(const Key& key, Clock::time_point expiration,
               TimeOutCallback callback) noexcept;
@@ -212,6 +214,7 @@ class HeapTimer {
     std::optional<std::size_t> Parent(std::size_t idx) const noexcept;
 
     /**
+     * @brief
      * Get the index of a node's child that has a shorter expiration time,
      * or @p std::nullopt if it does not exist.
      */

include/containers/thread_pool.h

@@ -26,9 +26,7 @@
 
 namespace ws {
 
-/**
- * The thread pool.
- */
+//! The thread pool.
 class ThreadPool {
 public:
     using Task = std::function<void()>;
@@ -62,15 +60,16 @@ class ThreadPool {
     void Push(Task task) noexcept;
 
     /**
-     * Close the thread pool.
+     * @brief Close the thread pool.
+     *
+     * @details
      * The remaining tasks will not be executed.
      */
     void Close() noexcept;
 
 private:
     /**
-     * @brief
-     * Continually pop and execute tasks.
+     * @brief Continually pop and execute tasks.
      *
      * @warning
      * Any exceptions raised in callbacks will not be rethrown.

include/http.h

@@ -69,6 +69,7 @@ std::ostream& operator<<(std::ostream& os, Method method) noexcept;
 inline constexpr std::string_view new_line {"\r\n"};
 
 /**
+ * @brief
  * Get a file's content type.
  * @p application/octet-stream is used to indicate that a file contains arbitrary binary data.
  */
@@ -93,6 +94,7 @@ char DecodeURLEncodedCharacter(const std::string& str);
 std::string DecodeURLEncodedString(const std::string& str);
 
 /**
+ * @brief
  * Get the HTML placeholder for an HTTP parameter.
  * It can be used to insert actual data into an HTML page.
  */
@@ -188,9 +190,7 @@ class ConnectionImpl {
     MappedReadOnlyFile file_;
 };
 
-/**
- * The HTTP connection.
- */
+//! The HTTP connection.
 template <ValidIPAddr IPAddr>
 class Connection : public ConnectionImpl {
 public:

include/io.h

@@ -25,10 +25,7 @@ class Buffer;
 
 namespace io {
 
-/**
- * @interface IReader
- * @brief An I/O reading interface interacting with buffers.
- */
+//! An I/O reading interface interacting with buffers.
 class IReader {
 public:
     virtual ~IReader() noexcept = default;
@@ -37,10 +34,7 @@ class IReader {
     virtual std::size_t ReadFrom(Buffer& buf) = 0;
 };
 
-/**
- * @interface IWriter
- * @brief An I/O writing interface interacting with buffers.
- */
+//! An I/O writing interface interacting with buffers.
 class IWriter {
 public:
     virtual ~IWriter() noexcept = default;
@@ -49,14 +43,13 @@ class IWriter {
     virtual std::size_t WriteTo(Buffer& buf) = 0;
 };
 
-/**
- * @interface IReadWriter
- * @brief An I/O interface interacting with buffers.
- */
+//! An I/O interface interacting with buffers.
 class IReadWriter : public virtual IReader, public virtual IWriter {};
 
 /**
- * Null I/O.
+ * @brief Null I/O.
+ *
+ * @details
  * It simply consumes a buffer's all readable or writable space,
  * without reading or writing anything.
  */
@@ -67,9 +60,7 @@ class Null : public virtual IReadWriter {
     std::size_t ReadFrom(Buffer& buf) noexcept override;
 };
 
-/**
- * I/O for string streams.
- */
+//! I/O for string streams.
 class StringStream : public virtual IReadWriter {
 public:
     /**
@@ -105,9 +96,7 @@ class StringStream : public virtual IReadWriter {
     std::ostream& write_;
 };
 
-/**
- * I/O for file descriptors.
- */
+//! I/O for file descriptors.
 class FileDescriptor : public virtual IReadWriter {
 public:
     /**
@@ -135,14 +124,8 @@ class FileDescriptor : public virtual IReadWriter {
 
     FileDescriptor& operator=(FileDescriptor&&) = delete;
 
-    /**
-     * @exception std::system_error Failed to read data from the descriptor.
-     */
     std::size_t WriteTo(Buffer& buf) override;
 
-    /**
-     * @exception std::system_error Failed to write data to the descriptor.
-     */
     std::size_t ReadFrom(Buffer& buf) override;
 
 private: