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);
diff --git a/docs/index.rst b/docs/index.rst
index 38a1253..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
@@ -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
^^^^^^^^^^^^^^^^
diff --git a/include/errors/error.hpp b/include/errors/error.hpp
index 9cfa8b3..ce0b78a 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:
@@ -24,29 +50,31 @@ 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;
/**
- * @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;
@@ -61,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
*/
@@ -79,12 +106,36 @@ 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);
/**
* @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();