docs: update API documentation (#139)

* docs(api): separate `errors::make` and `errors::nil` from `errors::Error`

* docs(api): link classes and functions to the API docs

* docs(api): update the API documentation of `errors::Error` class

* docs(api): update the API documentation of `errors::Error::message` method

* docs(api): update the API documentation of `errors::Error::operator bool` method

* docs(api): update the API documentation of `errors::operator<<` method

* docs(api): update the API documentation of `errors::make` function

* docs(api): update the API documentation of `errors::nil` function

* docs(api): update the API documentation of `errors::format` function

Author: threeal

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 <a href="https://fmt.dev/latest/syntax.html">fmtlib's formatting syntax</a>
+ * 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 <typename... T>
 Error format(fmt::format_string<T...> fmt, T&&... args);

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
 ^^^^^^^^^^^^^^^^

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();