docs: add usage section in readme and docs

README.md

@@ -46,6 +46,49 @@ add_executable(foo foo.cpp)
 target_link_libraries(foo PRIVATE errors::errors)
 ```
 
+## Usage
+
+This package contains an `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.
+
+```cpp
+errors::Error read_file(const char* filepath);
+
+int main() {
+ const auto err = read_file(filepath);
+ if (err) {
+ // Handle the error.
+ }
+
+ // 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.
+
+```cpp
+errors::Error read_file(const char* filepath) {
+ std::ifstream file(filepath);
+ if (!file.is_open()) {
+ return errors::make("failed to open file");
+ }
+
+ // Process with no error.
+
+ return errors::nil();
+}
+```
+
+Alternatively, an error object can also be created with a formatted message in the style of fmtlib using `errors::format` function.
+
+```cpp
+if (!file.is_open()) {
+ return errors::format("failed to open '{}'", filepath);
+}
+```
+
+For more details and examples, refer to the [examples](./examples) directory.
+
 ## License
 
 This project is licensed under the terms of the [MIT License](./LICENSE).

docs/index.rst

@@ -54,6 +54,53 @@ Alternatively, you can integrate this package using `CPM.cmake`_:
 .. _CMake: https://cmake.org/
 .. _CPM.cmake: https:/cpm-cmake/CPM.cmake
 
+
+Usage
+-----
+
+This package contains an `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
+
+ errors::Error read_file(const char* filepath);
+
+ int main() {
+ const auto err = read_file(filepath);
+ if (err) {
+ // Handle the error.
+ }
+
+ // 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.
+
+.. code-block:: cpp
+
+ errors::Error read_file(const char* filepath) {
+ std::ifstream file(filepath);
+ if (!file.is_open()) {
+ return errors::make("failed to open file");
+ }
+
+ // Process with no error.
+
+ return errors::nil();
+ }
+
+Alternatively, an error object can also be created with a formatted message in the style of fmtlib using `errors::format` function.
+
+.. code-block:: cpp
+
+ if (!file.is_open()) {
+ return errors::format("failed to open '{}'", filepath);
+ }
+
+For more details and examples, refer to the `examples`_ directory.
+
+.. _examples: https:/threeal/errors-cpp/tree/main/examples
+
 API Docs
 --------