From 44aacc2cbb43344394caa4caef761df6e4da43b6 Mon Sep 17 00:00:00 2001
From: Prodesire <prodesire@yeah.net>
Date: Fri, 17 Nov 2017 08:33:28 +0800
Subject: [PATCH] add doc for memoize and memoize_when_activated

---
 docs/misc.rst  | 50 +++++++++++++++++++++++++++++++++++++++++++++++---
 pydu/compat.py |  1 +
 pydu/string.py |  1 +
 3 files changed, 49 insertions(+), 3 deletions(-)

diff --git a/docs/misc.rst b/docs/misc.rst
index 704f387..75d46ee 100644
--- a/docs/misc.rst
+++ b/docs/misc.rst
@@ -1,7 +1,7 @@
 Miscellanea
 -----------
 
-.. py:function:: pydu.unix_timeout(seconds)
+.. py:function:: pydu.misc.unix_timeout(seconds)
 
   This func decorates any func which may be hang for a while. The param ``seconds``
   should be integer.
@@ -21,14 +21,14 @@ Miscellanea
   .. note:: ``unix_timeout`` can only be used on ``unix-like`` system.
 
 
-.. py:function:: pydu.trace(obj)
+.. py:function:: pydu.misc.trace(obj)
 
   Tracing every statement and line number for running program, like ``bash -x``.
   In `test.py`, you may write like below:
 
   .. code-block:: python
 
-    from pydu import trace
+    from pydu.misc import trace
     @trace
     def f():
         print(1)
@@ -47,3 +47,47 @@ Miscellanea
     test.py(6):     b = [a]
     test.py(7):     print(2)
     2
+
+
+.. py:function:: pydu.misc.memoize(obj)
+
+  A simple memoize decorator for functions supporting (hashable)
+  positional arguments.
+  It also provides a ``cache_clear()`` function for clearing the cache.
+
+  >>> @memoize
+  ... def foo()
+  ...     return 1
+      ...
+  >>> foo()
+  1
+  >>> foo.cache_clear()
+  >>>
+
+
+.. py:function:: pydu.misc.memoize_when_activated(obj)
+
+  A memoize decorator which is disabled by default. It can be
+  activated and deactivated on request.
+  For efficiency reasons it can be used only against class methods
+  accepting no arguments.
+
+  >>> class Foo:
+  ...     @memoize
+  ...     def foo()
+  ...         print(1)
+  ...
+  >>> f = Foo()
+  >>> # deactivated (default)
+  >>> foo()
+  1
+  >>> foo()
+  1
+  >>>
+  >>> # activated
+  >>> foo.cache_activate()
+  >>> foo()
+  1
+  >>> foo()
+  >>> foo()
+  >>>
diff --git a/pydu/compat.py b/pydu/compat.py
index 0444588..b25e951 100644
--- a/pydu/compat.py
+++ b/pydu/compat.py
@@ -10,6 +10,7 @@ if PY2:
 else:
     from urllib.parse import urljoin
 
+# TODO doc
 # Dictionary iteration
 if PY2:
     iterkeys = lambda d: d.iterkeys()
diff --git a/pydu/string.py b/pydu/string.py
index c8522c7..a61f601 100644
--- a/pydu/string.py
+++ b/pydu/string.py
@@ -24,6 +24,7 @@ def safeunicode(obj, encoding='utf-8'):
         return text_type(obj)
 
 
+# TODO doc
 def safestr(obj, encoding='utf-8'):
     r"""
     Converts any given object to utf-8 encoded string.