From 305db333bf154ad6578b2d6f7a6410db7fdbbcf9 Mon Sep 17 00:00:00 2001 From: AWE Henry Date: Thu, 13 Jun 2024 18:29:54 +0800 Subject: [PATCH] Update comments and Doxyfile --- include/papilio/color.hpp | 33 ++++++++++++++ include/papilio/container.hpp | 27 +++++++++++ include/papilio/core.hpp | 85 ++++++++++++++++++++++++++++++++++- include/papilio/core.inl | 6 +++ include/papilio/fmtfwd.hpp | 6 ++- include/papilio/format.hpp | 7 ++- include/papilio/locale.hpp | 26 ++++++++++- include/papilio/macros.hpp | 26 ++++++++--- include/papilio/memory.hpp | 25 ++++++++++- include/papilio/papilio.hpp | 17 +++++++ include/papilio/print.hpp | 6 +++ include/papilio/utf/utf.hpp | 9 ++++ include/papilio/utility.hpp | 6 ++- script/Doxyfile.in | 2 +- 14 files changed, 267 insertions(+), 14 deletions(-) diff --git a/include/papilio/color.hpp b/include/papilio/color.hpp index 2c0d087..7d7a42a 100644 --- a/include/papilio/color.hpp +++ b/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, char> : public formatter } }; +/** + * @brief Wrap a value with styling information. + * + * @param st Test style data + * @param val Value to output + */ PAPILIO_EXPORT template auto styled(text_style st, const T& val) { diff --git a/include/papilio/container.hpp b/include/papilio/container.hpp index 0f10640..a6f4912 100644 --- a/include/papilio/container.hpp +++ b/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 > 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 struct is_transparent : public std::bool_constant> diff --git a/include/papilio/core.hpp b/include/papilio/core.hpp index b681924..4aa4f0b 100755 --- a/include/papilio/core.hpp +++ b/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 [[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; PAPILIO_EXPORT template inline constexpr bool is_variable_storable_v = is_variable_storable::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 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 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 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) { diff --git a/include/papilio/core.inl b/include/papilio/core.inl index 1e8fe81..20c8965 100644 --- a/include/papilio/core.inl +++ b/include/papilio/core.inl @@ -1,3 +1,9 @@ +/** + * @file core.inl + * @author HenryAWE + * @brief Implementation of the core module. + */ + #include namespace papilio diff --git a/include/papilio/fmtfwd.hpp b/include/papilio/fmtfwd.hpp index 909629e..3e96d47 100644 --- a/include/papilio/fmtfwd.hpp +++ b/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 diff --git a/include/papilio/format.hpp b/include/papilio/format.hpp index 189897b..768e272 100644 --- a/include/papilio/format.hpp +++ b/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, CharT> #include "formatter/misc.hpp" #endif - diff --git a/include/papilio/locale.hpp b/include/papilio/locale.hpp index 909b0ec..2ae9e38 100644 --- a/include/papilio/locale.hpp +++ b/include/papilio/locale.hpp @@ -1,3 +1,9 @@ +/** + * @file locale.hpp + * @author HenryAWE + * @brief Locale support. + */ + #ifndef PAPILIO_LOCALE_HPP #define PAPILIO_LOCALE_HPP @@ -11,8 +17,6 @@ namespace papilio { /** * @brief Reference to a locale object. - * - * The member function `get()` will return `std::locale::classic()` if the reference is empty. */ PAPILIO_EXPORT class locale_ref { @@ -40,15 +44,33 @@ PAPILIO_EXPORT class locale_ref return *this; } + /** + * @brief Check if the reference is empty. + * + * @return true If the reference is empty. + * @return false If the reference is not empty. + */ [[nodiscard]] bool empty() const noexcept { return m_loc == nullptr; } + /** + * @brief Get the referenced locale object. + * + * If the reference is empty, `std::locale::classic()` will be returned. + * + * @return std::locale The locale object. + */ [[nodiscard]] std::locale get() const; + /** + * @brief A shortcut for `get()`. + * + * @return std::locale The locale object. + */ operator std::locale() const { return get(); diff --git a/include/papilio/macros.hpp b/include/papilio/macros.hpp index 7be1896..7fd95d6 100644 --- a/include/papilio/macros.hpp +++ b/include/papilio/macros.hpp @@ -1,3 +1,9 @@ +/** + * @file macros.hpp + * @author HenryAWE + * @brief Header of macro definitions. + */ + #ifndef PAPILIO_MACROS_HPP #define PAPILIO_MACROS_HPP @@ -14,12 +20,16 @@ #define PAPILIO_VERSION_MINOR 3 #define PAPILIO_VERSION_PATCH 0 -// Currently, this macro is just an alias of the assert() macro. -// It might be changed to a custom implementation for providing more information. +/** + * Currently, this macro is just an alias of the `assert()` macro. + * It might be changed to a custom implementation for providing more information. + */ #define PAPILIO_ASSERT(expr) assert(expr) -// Use this macro to avoid errors caused by ADL, -// especially when mixing this library and the standard . +/** + * Use this macro to avoid errors caused by ADL, + * especially when mixing this library and the standard . +*/ #define PAPILIO_NS ::papilio:: #if defined PAPILIO_COMPILER_MSVC @@ -37,7 +47,13 @@ # define PAPILIO_NO_UNIQUE_ADDRESS #endif -#define PAPILIO_STRINGIZE(text) #text +/** + * @brief Stringize given text. + */ +#define PAPILIO_STRINGIZE(text) #text +/** + * @brief Stringize given text without expanding any macros in it. + */ #define PAPILIO_STRINGIZE_EX(text) PAPILIO_STRINGIZE(text) #define PAPILIO_TSTRING_EX(char_t, str, suffix, decl) \ diff --git a/include/papilio/memory.hpp b/include/papilio/memory.hpp index b82e27f..7d30d83 100644 --- a/include/papilio/memory.hpp +++ b/include/papilio/memory.hpp @@ -1,3 +1,9 @@ +/** + * @file memory.hpp + * @author HenryAWE + * @brief Memory management utilities. + */ + #ifndef PAPILIO_MEMORY_HPP #define PAPILIO_MEMORY_HPP @@ -10,6 +16,12 @@ namespace papilio { +/** + * @brief Aligned static storage + * + * @tparam Capacity Maximum size of storage in bytes + * @tparam Align Alignment of storage + */ PAPILIO_EXPORT template < std::size_t Capacity, std::size_t Align = alignof(std::max_align_t)> @@ -41,6 +53,9 @@ class static_storage alignas(Align) std::byte m_data[Capacity]; }; +/** + * @brief Specialization of `static_storage` for zero capacity. + */ PAPILIO_EXPORT template class static_storage<0, Align> { @@ -126,8 +141,14 @@ namespace detail }; } // namespace detail -// Smart pointer that owns an optional ownership of another object. -// It can acts like a unique_ptr or a raw pointer. +/** + * @brief Smart pointer that owns an optional ownership of another object. + * + * The `optional_unique_ptr` acts like a `unique_ptr` or a raw pointer depending on its ownership state. + * + * @tparam T Element type + * @tparam Deleter Deleter + */ PAPILIO_EXPORT template < typename T, typename Deleter = std::default_delete> diff --git a/include/papilio/papilio.hpp b/include/papilio/papilio.hpp index 8b4a9dd..bdfdd20 100644 --- a/include/papilio/papilio.hpp +++ b/include/papilio/papilio.hpp @@ -1,3 +1,12 @@ +/** + * @file papilio.hpp + * @author HenryAWE + * @brief Main header file of the library + * + * @note Although this header will automatically include most of the library, + * some format support for seldom used types still need to be included separately. + */ + #ifndef PAPILIO_PAPILIO_HPP #define PAPILIO_PAPILIO_HPP @@ -10,12 +19,20 @@ #include "print.hpp" #include "detail/prefix.hpp" +/** + * @brief The main namespace of Papilio Charontis + */ namespace papilio { PAPILIO_EXPORT inline constexpr int version_major = PAPILIO_VERSION_MAJOR; PAPILIO_EXPORT inline constexpr int version_minor = PAPILIO_VERSION_MINOR; PAPILIO_EXPORT inline constexpr int version_patch = PAPILIO_VERSION_PATCH; +/** + * @brief Get the version number + * + * @return constexpr std::tuple The version number + */ PAPILIO_EXPORT [[nodiscard]] constexpr inline std::tuple get_version() noexcept diff --git a/include/papilio/print.hpp b/include/papilio/print.hpp index 6254920..45d3d58 100644 --- a/include/papilio/print.hpp +++ b/include/papilio/print.hpp @@ -1,3 +1,9 @@ +/** + * @file print.hpp + * @author HenryAWE + * @brief Functions for printing to terminal. + */ + #ifndef PAPILIO_PRINT_HPP #define PAPILIO_PRINT_HPP diff --git a/include/papilio/utf/utf.hpp b/include/papilio/utf/utf.hpp index c06e0c7..1fd9935 100644 --- a/include/papilio/utf/utf.hpp +++ b/include/papilio/utf/utf.hpp @@ -7,4 +7,13 @@ #include "codepoint.hpp" #include "string.hpp" +namespace papilio +{ +/** + * @brief Utilities for Unicode processing + */ +namespace utf +{} +} // namespace papilio + #endif diff --git a/include/papilio/utility.hpp b/include/papilio/utility.hpp index d1b8d4b..6424384 100644 --- a/include/papilio/utility.hpp +++ b/include/papilio/utility.hpp @@ -1,4 +1,8 @@ -// concepts, type traits, tags, auxiliary types +/** + * @file utility.hpp + * @author HenryAWE + * @brief Header of concepts, type traits, tags, and auxiliary types. + */ #ifndef PAPILIO_UTILITY_HPP #define PAPILIO_UTILITY_HPP diff --git a/script/Doxyfile.in b/script/Doxyfile.in index 4470d62..5dc0407 100644 --- a/script/Doxyfile.in +++ b/script/Doxyfile.in @@ -938,7 +938,7 @@ EXCLUDE_PATTERNS = # Note that the wildcards are matched against the file with absolute path, so to # exclude all test directories use the pattern */test/* -EXCLUDE_SYMBOLS = +EXCLUDE_SYMBOLS = *::detail::* # The EXAMPLE_PATH tag can be used to specify one or more files or directories # that contain example code fragments that are included (see the \include