More docs

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, "

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
 =================

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.
+