From bd7bda85bc5d4e8984519321e4843b4880e8e271 Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@koston.org>
Date: Sat, 5 Oct 2024 18:50:25 -0500
Subject: [PATCH] Add api docs

---
 docs/api.rst   | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++
 docs/index.rst | 10 ++++++++++
 2 files changed, 64 insertions(+)
 create mode 100644 docs/api.rst

diff --git a/docs/api.rst b/docs/api.rst
new file mode 100644
index 0000000..5e32d62
--- /dev/null
+++ b/docs/api.rst
@@ -0,0 +1,54 @@
+.. _propcache-reference:
+
+============
+Reference
+============
+
+.. module:: propcache
+
+
+
+cached_property
+===============
+
+.. decorator:: cached_property(func)
+
+   This decorator functions exactly the same as the standard library
+   :func:`cached_property` decorator, but it's available in the
+   :mod:`propcache` module along with an accelerated Cython version.
+
+   As with the standard library version, the cached value is stored in
+   the instance's ``__dict__`` dictionary. To clear a cached value, you
+   can use the :meth:`del` operator on the instance's attribute or call
+   ``instance.__dict__.pop('attribute_name', None)``.
+
+under_cached_property
+=====================
+
+.. decorator:: under_cached_property(func)
+
+   Transform a method of a class into a property whose value is computed
+   only once and then cached as a private attribute. Similar to the
+   :func:`cached_property` decorator, but the cached value is stored
+   in the instance's ``_cache`` dictionary instead of ``__dict__``.
+
+   Example::
+
+       class MyClass:
+
+           def __init__(self, data: List[float]):
+               self._data = data
+               self._cache = {}
+
+           @cached_property
+           def calculated_data(self):
+               return expensive_operation(self._data)
+
+           def clear_cache(self):
+               self._cache.clear()
+
+       instance = MyClass([1.0, 2.0, 3.0])
+       print(instance.calculated_data)  # expensive operation
+
+       instance.clear_cache()
+       print(instance.calculated_data)  # expensive operation
diff --git a/docs/index.rst b/docs/index.rst
index 03c6357..a36d0ed 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -18,6 +18,11 @@ The API is designed to be nearly identical to the built-in ``cached_property`` c
 except for the additional ``under_cached_property`` class which uses ``self._cache``
 instead of ``self.__dict__`` to store the cached values and prevents ``__set__`` from being called.
 
+API documentation
+------------------
+
+Open :ref:`propcache-api` for reading full list of available methods.
+
 Source code
 -----------
 
@@ -46,6 +51,11 @@ It's *Apache 2* licensed and freely available.
 
 Contents:
 
+.. toctree::
+   :maxdepth: 2
+
+   api
+
 .. toctree::
    :caption: What's new