docs: improve guides in readme and documentation (#120)

* docs: update project description in readme and docs

* docs: add key features section in readme and docs

* docs: add integration section in readme and docs

* docs: add usage section in readme and docs

Author: threeal

README.md

@@ -4,7 +4,90 @@
 [![test status](https://img.shields.io/github/actions/workflow/status/threeal/errors-cpp/test.yaml?branch=main&&label=test)](https://github.com/threeal/errors-cpp/actions/workflows/test.yaml)
 [![deploy status](https://img.shields.io/github/actions/workflow/status/threeal/errors-cpp/deploy.yaml?branch=main&label=deploy)](https://github.com/threeal/errors-cpp/actions/workflows/deploy.yaml)
 
-A C++ package that provides utilities for error handling.
+Error C++ is a [C++](https://isocpp.org/) 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 serves as an alternative to error handling using [try-catch exceptions](https://en.cppreference.com/w/cpp/language/try_catch), commonly found in C++ code.
+It facilitates error handling by returning values, following the style of [Go's error handling](https://go.dev/blog/error-handling-and-go).
+
+## 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](https://github.com/fmtlib/fmt) using `errors::format`.
+- Direct printing of `errors::Error` using C++ streams and fmtlib.
+
+## Integration
+
+To integrate this package into your C++ project, you can build and install it locally using [CMake](https://cmake.org/):
+
+```sh
+cmake -B build .
+cmake --build build --config Release
+cmake --install build
+```
+
+Once installed, you can use it in your CMake project as the `Errors` package:
+
+```cmake
+find_package(Errors 1.0.0 REQUIRED CONFIG)
+
+add_executable(foo foo.cpp)
+target_link_libraries(foo PRIVATE errors::errors)
+```
+
+Alternatively, you can also integrate this package using [CPM.cmake](https://github.com/cpm-cmake/CPM.cmake):
+
+```cmake
+cpmaddpackage(gh:threeal/errors-cpp@1.0.0)
+
+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
 

docs/index.rst

@@ -1,9 +1,105 @@
 Errors C++
 =============
 
-A `C++`_ package that provides utilities for error handling.
+Error 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 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`_.
 
 .. _C++: https://isocpp.org
+.. _try-catch exceptions: https://en.cppreference.com/w/cpp/language/try_catch
+.. _Go's error handling: https://go.dev/blog/error-handling-and-go
+
+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.
+
+.. _fmtlib: https://github.com/fmtlib/fmt
+
+Integration
+-----------
+
+To integrate this package into your C++ project, you can build and install it locally using `CMake`_:
+
+.. code-block:: sh
+
+   cmake -B build .
+   cmake --build build --config Release
+   cmake --install build
+
+Once installed, you can use it in your CMake project as the `Errors` package:
+
+.. code-block:: cmake
+
+   find_package(Errors 1.0.0 REQUIRED CONFIG)
+
+   add_executable(foo foo.cpp)
+   target_link_libraries(foo PRIVATE errors::errors)
+
+Alternatively, you can also integrate this package using `CPM.cmake`_:
+
+.. code-block:: cmake
+
+   cpmaddpackage(gh:threeal/errors-cpp@1.0.0)
+
+   add_executable(foo foo.cpp)
+   target_link_libraries(foo PRIVATE errors::errors)
+
+.. _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
 --------