Update comments and Doxyfile

include/papilio/color.hpp

@@ -1,3 +1,9 @@
+/**
+ * @file color.hpp
+ * @author HenryAWE
+ * @brief Styled terminal output support.
+ */
+
 #ifndef PAPILIO_COLOR_HPP
 #define PAPILIO_COLOR_HPP
 
@@ -11,6 +17,9 @@ namespace papilio
 {
 PAPILIO_EXPORT class text_style;
 
+/**
+ * @brief Terminal output color
+ */
 PAPILIO_EXPORT enum class color : std::uint8_t
 {
     none = 0,
@@ -24,6 +33,9 @@ PAPILIO_EXPORT enum class color : std::uint8_t
     white = 37
 };
 
+/**
+ * @brief Terminal output style 
+ */
 PAPILIO_EXPORT enum class style : std::uint8_t
 {
     none = 0,
@@ -33,10 +45,25 @@ PAPILIO_EXPORT enum class style : std::uint8_t
     underline = 1 << 3
 };
 
+/**
+ * @brief Set the foreground color.
+ *
+ * @param col Color
+ * @return text_style Text style data
+ */
 PAPILIO_EXPORT text_style fg(color col) noexcept;
 
+/**
+ * @brief Set the background color.
+ *
+ * @param col Color
+ * @return text_style Text style data
+ */
 PAPILIO_EXPORT text_style bg(color col) noexcept;
 
+/**
+ * @brief Terminal output text style
+ */
 PAPILIO_EXPORT class text_style
 {
 public:
@@ -227,6 +254,12 @@ class formatter<detail::styled_arg<T>, char> : public formatter<T>
     }
 };
 
+/**
+ * @brief Wrap a value with styling information.
+ * 
+ * @param st Test style data
+ * @param val Value to output
+ */
 PAPILIO_EXPORT template <typename T>
 auto styled(text_style st, const T& val)
 {

include/papilio/container.hpp

@@ -1,3 +1,9 @@
+/**
+ * @file container.hpp
+ * @author HenryAWE
+ * @brief Some useful non-STL containers.
+ */
+
 #ifndef PAPILIO_CONTAINER_HPP
 #define PAPILIO_CONTAINER_HPP
 
@@ -36,6 +42,14 @@ namespace detail
     };
 } // namespace detail
 
+/**
+ * @brief The base class of a `small_vector`.
+ * 
+ * This class can be used if the user code does not need to know the size of the static capacity.
+ *
+ * @tparam T Type of the elements
+ * @tparam Allocator The allocator for dynamically allocating memory
+ */
 PAPILIO_EXPORT template <typename T, typename Allocator = std::allocator<T>>
 class small_vector_base : public detail::small_vector_impl
 {
@@ -226,6 +240,16 @@ class small_vector_base : public detail::small_vector_impl
     }
 };
 
+/**
+ * @brief Small vector that acts like a `std::vector`.
+ *
+ * The small_vector will store elements in a pre-allocated memory block.
+ * If the size exceeds the static capacity, it will dynamically allocate memory to store the elements.
+ *
+ * @tparam T Type of the elements
+ * @tparam StaticCapacity Static capacity of the small vector
+ * @tparam Allocator The allocator for dynamically allocating memory
+ */
 PAPILIO_EXPORT template <
     typename T,
     std::size_t StaticCapacity,
@@ -1173,6 +1197,9 @@ namespace detail
     };
 } // namespace detail
 
+/**
+ * @brief Check if a comparator is transparent, i.e. supporting heterogeneous compare.
+ */
 PAPILIO_EXPORT template <typename Compare>
 struct is_transparent :
     public std::bool_constant<detail::is_transparent_helper<Compare>>

include/papilio/core.hpp

@@ -1,3 +1,9 @@
+/**
+ * @file core.hpp
+ * @author HenryAWE
+ * @brief The core module of library.
+ */
+
 #ifndef PAPILIO_CORE_HPP
 #define PAPILIO_CORE_HPP
 
@@ -23,6 +29,9 @@
 
 namespace papilio
 {
+/**
+* @brief Format error
+*/
 PAPILIO_EXPORT class format_error : public std::runtime_error
 {
 public:
@@ -78,6 +87,11 @@ class basic_format_string
 
     constexpr basic_format_string& operator=(const basic_format_string&) noexcept = default;
 
+    /**
+     * @brief Get the format string.
+     *
+     * @return string_view_type The format string.
+     */
     [[nodiscard]]
     constexpr string_view_type get() const noexcept
     {
@@ -88,6 +102,9 @@ class basic_format_string
     string_view_type m_fmt;
 };
 
+/**
+ * @brief The script error code
+ */
 PAPILIO_EXPORT enum class script_error_code : int
 {
     no_error = 0,
@@ -111,6 +128,9 @@ std::wstring to_wstring(script_error_code ec);
 std::ostream& operator<<(std::ostream& os, script_error_code ec);
 std::wostream& operator<<(std::wostream& os, script_error_code ec);
 
+/**
+ * @brief Formatter data for standard format specification
+ */
 PAPILIO_EXPORT struct std_formatter_data
 {
     using size_type = std::size_t;
@@ -162,6 +182,11 @@ PAPILIO_EXPORT struct std_formatter_data
     }
 };
 
+/**
+ * @brief Formatter data for simple formatter data.
+ *
+ * Simple formatter data only contains width, filling character, alignment, and locale.
+ */
 PAPILIO_EXPORT struct simple_formatter_data
 {
     using size_type = std::size_t;
@@ -183,6 +208,11 @@ PAPILIO_EXPORT struct simple_formatter_data
         return has_fill() ? fill : val;
     }
 
+    /**
+     * @brief Convert the simple formatter data to standard formatter data.
+     * 
+     * @return std_formatter_data The data for standard format specification.
+     */
     constexpr std_formatter_data to_std_data() const noexcept
     {
         return std_formatter_data{
@@ -209,6 +239,9 @@ PAPILIO_EXPORT class bad_variable_access : public std::bad_variant_access
     ~bad_variable_access();
 };
 
+/**
+ * @brief Invalid conversion error
+ */
 PAPILIO_EXPORT class invalid_conversion : public std::invalid_argument
 {
 public:
@@ -347,6 +380,11 @@ class basic_variable : public variable_base
     basic_variable& operator=(const basic_variable&) = default;
     basic_variable& operator=(basic_variable&&) noexcept = default;
 
+    /**
+     * @brief Checks if the variable holds a value of the given type.
+     *
+     * @tparam T Type to check against.
+     */
     template <typename T>
     [[nodiscard]]
     bool holds() const noexcept
@@ -431,6 +469,14 @@ class basic_variable : public variable_base
         return m_var;
     }
 
+    /**
+     * @brief Compares two variables.
+     * 
+     * This function compares two variables and returns a value indicating their relationship.
+     * 
+     * @param var Another variable to compare with.
+     * @return std::partial_ordering The relationship between two variables.
+     */
     [[nodiscard]]
     std::partial_ordering compare(const basic_variable& var) const noexcept
     {
@@ -449,6 +495,15 @@ class basic_variable : public variable_base
         return compare(rhs);
     }
 
+    /**
+     * @brief Checks if two variables are equal.
+     * 
+     * This function checks if two variables are equal within the specified epsilon.
+     * 
+     * @param var Another variable to compare with.
+     * @param epsilon The maximum difference allowed between two variables.
+     *                This parameter is only used when one variable holds a float value.
+     */
     [[nodiscard]]
     bool equal(
         const basic_variable& var,
@@ -609,6 +664,9 @@ using is_variable_storable = is_basic_variable_storable<T, char>;
 PAPILIO_EXPORT template <typename T>
 inline constexpr bool is_variable_storable_v = is_variable_storable<T>::value;
 
+/**
+ * @brief Bad handle cast
+ */
 PAPILIO_EXPORT class bad_handle_cast : public std::bad_cast
 {
 public:
@@ -620,6 +678,9 @@ PAPILIO_EXPORT class bad_handle_cast : public std::bad_cast
     }
 };
 
+/**
+ * @brief Default formatter. It does nothing.
+ */
 PAPILIO_EXPORT template <typename T, typename CharT>
 class formatter
 {
@@ -632,7 +693,11 @@ class formatter
     formatter& operator=(formatter&&) = delete;
 };
 
-// Derive your formatter from this class to explicitly prevent a type from being formatted.
+/**
+ * @brief Explicitly disabled formatter
+ *
+ * Derive your formatter from this class to explicitly prevent a type from being formatted
+ */
 PAPILIO_EXPORT class disabled_formatter
 {
     disabled_formatter() = delete;
@@ -884,6 +949,9 @@ class basic_format_arg
     };
 
 public:
+    /**
+     * @brief Type-erased handle to a value to be formatted.
+     */
     class handle
     {
     public:
@@ -1923,6 +1991,12 @@ namespace detail
         typename Context::char_type>::type;
 } // namespace detail
 
+/**
+ * @brief Format context
+ *
+ * @tparam OutputIt Output iterator
+ * @tparam CharT Char type
+ */
 PAPILIO_EXPORT template <typename OutputIt, typename CharT>
 class basic_format_context
 {
@@ -1978,6 +2052,9 @@ class basic_format_context
     locale_ref m_loc;
 };
 
+/**
+ * @brief Traits for the format context.
+ */
 PAPILIO_EXPORT template <typename Context>
 class format_context_traits
 {
@@ -1992,6 +2069,12 @@ class format_context_traits
 
     format_context_traits() = delete;
 
+    /**
+     * @brief Get the output iterator from the context.
+     *
+     * @param ctx The context
+     * @return iterator The output iterator
+     */
     [[nodiscard]]
     static iterator out(context_type& ctx)
     {

include/papilio/core.inl

@@ -1,3 +1,9 @@
+/**
+ * @file core.inl
+ * @author HenryAWE
+ * @brief Implementation of the core module.
+ */
+
 #include <sstream>
 
 namespace papilio

include/papilio/fmtfwd.hpp

@@ -1,4 +1,8 @@
-// Forward declarations
+/**
+ * @file fmtfwd.hpp
+ * @author HenryAWE
+ * @brief Forward declarations
+ */
 
 #ifndef PAPILIO_FMTFWD_HPP
 #define PAPILIO_FMTFWD_HPP

include/papilio/format.hpp

@@ -1,3 +1,9 @@
+/**
+ * @file format.hpp
+ * @author HenryAWE
+ * @brief Format APIs
+ */
+
 #ifndef PAPILIO_FORMAT_HPP
 #define PAPILIO_FORMAT_HPP
 
@@ -503,4 +509,3 @@ class formatter<joiner<R, CharT>, CharT>
 #include "formatter/misc.hpp"
 
 #endif
-