From a0f73c85ebcbdd0b4569c65e2c243f5b218044d7 Mon Sep 17 00:00:00 2001
From: Andrew Svetlov <andrew.svetlov@gmail.com>
Date: Thu, 29 Oct 2015 10:31:24 +0200
Subject: [PATCH] More docs

---
 aiohttp_security/api.py |  6 ++++++
 docs/reference.rst      | 22 +++++++++++++++++++++-
 docs/usage.rst          |  4 ++++
 3 files changed, 31 insertions(+), 1 deletion(-)
 create mode 100644 docs/usage.rst

diff --git a/aiohttp_security/api.py b/aiohttp_security/api.py
index 4ffea01..26cfdad 100644
--- a/aiohttp_security/api.py
+++ b/aiohttp_security/api.py
@@ -9,6 +9,12 @@ AUTZ_KEY = 'aiohttp_security_autz_policy'
 
 @asyncio.coroutine
 def remember(request, response, identity, **kwargs):
+    """Remember identity into response.
+
+    The action is performed by indentity_policy.remember()
+    Usually the idenity is stored in user cookies homehow.
+    """
+    assert isinstance(identity, str), identity
     identity_policy = request.app.get(IDENTITY_KEY)
     if identity_policy is None:
         text = ("Security subsystem is not initialized, "
diff --git a/docs/reference.rst b/docs/reference.rst
index 492b92c..308e4b6 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -15,13 +15,33 @@ Public API functions
 
 .. coroutine:: remember(request, response, identity, **kwargs)
 
-   Remember identity
+   Remember identity into response.
 
+   The action is performed by registered
+   :coroutinemethod:`AbstractIdentityPolicy.remember`.
+
+   Usually the *idenity* is stored in user cookies homehow for using by
+   :coroutine:`authorized_userid` and :coroutine:`permits`.
+
+   :param request: :class:`aiohttp.web.Request` object.
+
+   :param response: :class:`aiohttp.web.StreamResponse` and
+                    descendants like :class:`aiohttp.web.Response`.
+
+   :param str identity: :class:`aiohttp.web.Request` object.
 
 .. function:: setup(app, identity_policy, autz_policy)
 
    Setup :mod:`aiohttp` application with security policies.
 
+   :param app: aiohttp :class:`aiohttp.web.Application` instance.
+
+   :param identity_policy: indentification policy, an
+                           :class:`AbstractIdentityPolicy` instance.
+
+   :param autz_policy: authorization policy, an
+                           :class:`AbstractAuthorizationPolicy` instance.
+
 
 Abstract policies
 =================
diff --git a/docs/usage.rst b/docs/usage.rst
new file mode 100644
index 0000000..d4ef6c2
--- /dev/null
+++ b/docs/usage.rst
@@ -0,0 +1,4 @@
+identity is a string shared between browser and server.
+Thus it should not be database primary key etc.
+Random string like uuid or hash is better choice.
+