From b6ad686ab001889b867bcb28de29c300062e8739 Mon Sep 17 00:00:00 2001
From: HansBug <killog@126.com>
Date: Wed, 29 Dec 2021 13:01:19 +0800
Subject: [PATCH] dev(hansbug): add doc for delayed

---
 treevalue/tree/tree/tree.pyx | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/treevalue/tree/tree/tree.pyx b/treevalue/tree/tree/tree.pyx
index 2e0244173a..fc032e9c44 100644
--- a/treevalue/tree/tree/tree.pyx
+++ b/treevalue/tree/tree/tree.pyx
@@ -435,10 +435,42 @@ def delayed(func, *args, **kwargs):
     r"""
     Overview:
         Use delayed function in treevalue.
+        The given ``func`` will not be called until its value is accessed, and \
+        it will be only called once, after that the delayed node will be replaced by the actual value.
 
     Arguments:
         - func: Delayed function.
         - args: Positional arguments.
         - kwargs: Key-word arguments.
+
+    Examples::
+        >>> from treevalue import TreeValue, delayed
+        >>>
+        >>> def f(x):
+        >>>     print('f is called, x is', x)
+        >>>     return x ** x
+        >>>
+        >>> t = TreeValue({'a': delayed(f, 2), 'x': delayed(f, 3)})
+        >>> t.a
+        f is called, x is 2
+        4
+        >>> t.x
+        f is called, x is 3
+        27
+        >>> t.a
+        4
+        >>> t.x
+        27
+        >>> t = TreeValue({'a': delayed(f, 2), 'x': delayed(f, 3)})
+        >>> print(t)
+        f is called, x is 2
+        f is called, x is 3
+        <TreeValue 0x7f0fb7f03198>
+        ├── a --> 4
+        └── x --> 27
+        >>> print(t)
+        <TreeValue 0x7f0fb7f03198>
+        ├── a --> 4
+        └── x --> 27
     """
     return DetachedDelayedProxy(_c_delayed_partial(func, args, kwargs))
-- 
GitLab