From 1d6d548f13d67f8b5438a0c41dffd4b91397f267 Mon Sep 17 00:00:00 2001 From: Alfi Maulana Date: Thu, 4 Jan 2024 19:03:33 +0700 Subject: [PATCH 1/9] docs(api): separate `errors::make` and `errors::nil` from `errors::Error` --- docs/index.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index 38a1253..10f444b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -106,7 +106,13 @@ API Docs .. doxygenclass:: errors::Error :project: errors - :members: + :members: message, operator bool, operator<< + +.. doxygenfunction:: errors::make + :project: errors + +.. doxygenfunction:: errors::nil + :project: errors Format Component ^^^^^^^^^^^^^^^^ From b316d427d7013a42a3cdf1e657d6d0e24bfe710a Mon Sep 17 00:00:00 2001 From: Alfi Maulana Date: Thu, 4 Jan 2024 19:04:22 +0700 Subject: [PATCH 2/9] docs(api): link classes and functions to the API docs --- docs/index.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 10f444b..18cce5a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -2,7 +2,7 @@ Errors C++ ============= Errors C++ is a `C++`_ package that provides utilities for error handling. -This package mainly consists of the `errors::Error` class, representing an object that may contain an error. +This package mainly consists of the :cpp:class:`errors::Error` class, representing an object that may contain an error. This package serves as an alternative to error handling using `try-catch exceptions`_, commonly found in C++ code. It facilitates error handling by returning values, following the style of `Go's error handling`_. @@ -16,9 +16,9 @@ Key Features This package provides the following key features: -- Error handling in the style of Go by returning an `errors::Error`. -- Support for creating errors in the style of `fmtlib`_ using `errors::format`. -- Direct printing of `errors::Error` using C++ streams and fmtlib. +- Error handling in the style of Go by returning an :cpp:class:`errors::Error`. +- Support for creating errors in the style of `fmtlib`_ using :cpp:func:`errors::format`. +- Direct printing of :cpp:class:`errors::Error` using C++ streams and fmtlib. .. _fmtlib: https://github.com/fmtlib/fmt @@ -58,7 +58,7 @@ Alternatively, you can also integrate this package using `CPM.cmake`_: Usage ----- -This package contains an `errors::Error` class, which represents an error object. +This package contains an :cpp:class:`errors::Error` class, which represents an error object. Functions that may produce errors should return this object so that the error can be handled properly. .. code-block:: cpp @@ -74,7 +74,7 @@ Functions that may produce errors should return this object so that the error ca // Continue processing if no error. } -For functions returning `errors::Error`, use `errors::nil` function to signify no error or return an error object created from the `errors::make` function. +For functions returning :cpp:class:`errors::Error`, use :cpp:func:`errors::nil` function to signify no error or return an error object created from the :cpp:func:`errors::make` function. .. code-block:: cpp @@ -89,7 +89,7 @@ For functions returning `errors::Error`, use `errors::nil` function to signify n return errors::nil(); } -Alternatively, an error object can also be created with a formatted message in the style of fmtlib using `errors::format` function. +Alternatively, an error object can also be created with a formatted message in the style of fmtlib using :cpp:func:`errors::format` function. .. code-block:: cpp From c156aef22658f3949d5dbc02d6355715fa69b080 Mon Sep 17 00:00:00 2001 From: Alfi Maulana Date: Thu, 4 Jan 2024 19:04:41 +0700 Subject: [PATCH 3/9] docs(api): update the API documentation of `errors::Error` class --- include/errors/error.hpp | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/include/errors/error.hpp b/include/errors/error.hpp index 9cfa8b3..503c1af 100644 --- a/include/errors/error.hpp +++ b/include/errors/error.hpp @@ -14,6 +14,32 @@ namespace errors { /** * @brief Represents error information. + * + * Use this class as the return type for functions that may produce errors. + * This class has two state: either it contains an error or not. + * Use boolean operations to check whether an object contains an error or not. + * + * @code{.cpp} + * errors::Error print_hex(const char* number_str) { + * int number = std::atoi(number_str); + * if (number_str[0] != '0' && number == 0) { + * return errors::make("is not a number"); + * } + * + * std::cout << std::hex << number << std::endl; + * return errors::nil(); + * } + * + * int main() { + * // Print "7b". + * auto err = print_hex("123"); + * assert(!err); + * + * // Error. + * err = print_hex("not a number"); + * assert(err); + * } + * @endcode */ class [[nodiscard]] Error { private: From 25b965bd7644f8d207fecd3e481a6bf6f63b3f4e Mon Sep 17 00:00:00 2001 From: Alfi Maulana Date: Thu, 4 Jan 2024 19:04:42 +0700 Subject: [PATCH 4/9] docs(api): update the API documentation of `errors::Error::message` method --- include/errors/error.hpp | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/include/errors/error.hpp b/include/errors/error.hpp index 503c1af..4ecdb4e 100644 --- a/include/errors/error.hpp +++ b/include/errors/error.hpp @@ -50,12 +50,17 @@ class [[nodiscard]] Error { public: /** * @brief Returns the error message. + * @returns The error message. + * + * Returns the error message as a string view. + * If the object does not contain an error, it will return the string "no error" instead. * * @code{.cpp} * const auto err = errors::make("unknown error"); + * const auto no_err = errors::nil(); * - * // Print "unknown error" - * std::cout << err << std::endl; + * // Print "unknown error, no error". + * std::cout << err.message() << ", " << no_err.message() << std::endl; * @endcode */ std::string_view message() const; From d6c59cc2312d6cdfe54ada97511d785ba19f2280 Mon Sep 17 00:00:00 2001 From: Alfi Maulana Date: Thu, 4 Jan 2024 19:04:43 +0700 Subject: [PATCH 5/9] docs(api): update the API documentation of `errors::Error::operator bool` method --- include/errors/error.hpp | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/include/errors/error.hpp b/include/errors/error.hpp index 4ecdb4e..22122d7 100644 --- a/include/errors/error.hpp +++ b/include/errors/error.hpp @@ -66,18 +66,15 @@ class [[nodiscard]] Error { std::string_view message() const; /** - * @brief Checks whether the object contains an error. + * @brief Checks whether it contains an error or not. * @return `true` if it contains an error, otherwise `false`. * * @code{.cpp} * const auto err = errors::make("unknown error"); + * assert(err); * - * // Print "contains error". - * if (err) { - * std::cout << "contains error" << std::endl; - * } else { - * std::cout << "no error" << std::endl; - * } + * const auto no_err = errors::nil(); + * assert(!no_err); * @endcode */ explicit operator bool() const; From 6ff719ed1abbf889b1ac2253b5ba14f80731f8f3 Mon Sep 17 00:00:00 2001 From: Alfi Maulana Date: Thu, 4 Jan 2024 19:04:44 +0700 Subject: [PATCH 6/9] docs(api): update the API documentation of `errors::operator<<` method --- include/errors/error.hpp | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/include/errors/error.hpp b/include/errors/error.hpp index 22122d7..86e19b4 100644 --- a/include/errors/error.hpp +++ b/include/errors/error.hpp @@ -89,14 +89,13 @@ class [[nodiscard]] Error { * @param err The error object. * @return The output stream. * - * This operator allows an error object to be printed to the output stream - * using the << operator. The error message will be written to the output - * stream. + * This operator allows an error object to be printed to the output stream using the << operator. + * The error message will be written to the output stream. * * @code{.cpp} * const auto err = errors::make("unknown error"); * - * // Print "error: unknown error" + * // Print "error: unknown error". * std::cout << err << std::endl; * @endcode */ From fc81df2bcd14102772e0430adb3bdd87588e01e1 Mon Sep 17 00:00:00 2001 From: Alfi Maulana Date: Thu, 4 Jan 2024 19:04:44 +0700 Subject: [PATCH 7/9] docs(api): update the API documentation of `errors::make` function --- include/errors/error.hpp | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/include/errors/error.hpp b/include/errors/error.hpp index 86e19b4..be2321e 100644 --- a/include/errors/error.hpp +++ b/include/errors/error.hpp @@ -106,6 +106,18 @@ class [[nodiscard]] Error { * @brief Creates a new error object with the given message. * @param msg The error message. * @return A new error object. + * + * Use this function to create a new error object with the given message. + * Be aware that creating a new error object with an empty message will treat the object as containing an error. + * Use `errors::nil` instead if you want to create an empty error object. + * + * @code{.cpp} + * auto err = errors::make("unknown error"); + * assert(err); + * + * err = errors::make(""); + * assert(err); + * @endcode */ Error make(std::string_view msg); From ae3b874a874a4b6dae3c406c95dedd0258a3dada Mon Sep 17 00:00:00 2001 From: Alfi Maulana Date: Thu, 4 Jan 2024 19:04:45 +0700 Subject: [PATCH 8/9] docs(api): update the API documentation of `errors::nil` function --- include/errors/error.hpp | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/include/errors/error.hpp b/include/errors/error.hpp index be2321e..ce0b78a 100644 --- a/include/errors/error.hpp +++ b/include/errors/error.hpp @@ -124,6 +124,18 @@ Error make(std::string_view msg); /** * @brief Gets a constant reference of an empty error. * @return A constant reference of an empty error. + * + * Use this function to initialize a new empty error object. + * If copied onto another error object, it will set that object to be treated as not containing an error. + * + * @code{.cpp} + * const auto no_err = errors::nil(); + * assert(!no_err); + * + * auto err = errors::make("unknown error"); + * err = errors::nil(); + * assert(!err); + * @endcode */ const Error& nil(); From 2157a89e9ed16e0eaf7aa9d0831776da81d08435 Mon Sep 17 00:00:00 2001 From: Alfi Maulana Date: Thu, 4 Jan 2024 19:04:46 +0700 Subject: [PATCH 9/9] docs(api): update the API documentation of `errors::format` function --- components/format/include/errors/format.hpp | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/components/format/include/errors/format.hpp b/components/format/include/errors/format.hpp index 1afce86..7446236 100644 --- a/components/format/include/errors/format.hpp +++ b/components/format/include/errors/format.hpp @@ -12,6 +12,18 @@ namespace errors { * @param fmt A format string for the message. * @param args Format arguments. * @return A new error object. + * + * Use this function to create a new error object with a formatted message. + * Refer to fmtlib's formatting syntax + * for more information on formatting a message for the error object. + * + * @code{.cpp} + * const int code = 404; + * const auto err = errors::format("HTTP error {}", code); + * + * // Print "error: HTTP error 404". + * fmt::format("{}\n", err) + * @endcode */ template Error format(fmt::format_string fmt, T&&... args);