docs: add usage section in readme and docs

Author: threeal

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://github.com/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://github.com/threeal/errors-cpp/tree/main/examples
+
 API Docs
 --------