Work on documentation

aiohttp_security/api.py

@@ -28,6 +28,8 @@ def remember(request, response, identity, **kwargs):
 
 @asyncio.coroutine
 def forget(request, response):
+    """Forget previously remembered identity."""
+
     identity_policy = request.app.get(IDENTITY_KEY)
     if identity_policy is None:
         text = ("Security subsystem is not initialized, "

docs/glossary.rst

@@ -24,3 +24,18 @@
       Reference implementation of :pep:`3156`
 
       https://pypi.python.org/pypi/asyncio/
+
+   identity
+
+      Session-wide :class:`str` for identifying user.
+
+      Stored in local storage (client-side cookie or server-side storage).
+
+      Use :coroutine:`~aiohttp_session.remember` for saving *identity* (login)
+      and :coroutine:`~aiohttp_session.forget` for dropping it (logout).
+
+      *identity* is used for getting :term:`userid` and :term:`permissions`.
+
+   userid
+
+       User's ID, most likely his *login* or *email*

docs/reference.rst

@@ -15,7 +15,8 @@ Public API functions
 
 .. coroutine:: remember(request, response, identity, **kwargs)
 
-   Remember identity into response.
+   Remember *identity* in *response*, e.g. by storing a cookie or
+   saving info into session.
 
    The action is performed by registered
    :coroutinemethod:`AbstractIdentityPolicy.remember`.
@@ -30,6 +31,44 @@ Public API functions
 
    :param str identity: :class:`aiohttp.web.Request` object.
 
+   :param **kwargs: additional arguments passed to
+                    :coroutinemethod:`AbstractIdentityPolicy.remember`.
+
+                    They are policy-specific and may be used, e.g. for
+                    specifiying cookie lifetime.
+
+.. coroutine:: forget(request, response)
+
+   Forget previously remembered :term:`identity`.
+
+   The action is performed by registered
+   :coroutinemethod:`AbstractIdentityPolicy.forget`.
+
+   :param request: :class:`aiohttp.web.Request` object.
+
+   :param response: :class:`aiohttp.web.StreamResponse` and
+                    descendants like :class:`aiohttp.web.Response`.
+
+
+.. coroutine:: authorized_userid(request)
+
+   Retrieve :term:`userid`.
+
+   The user should be registered by :coroutine:`remember` before the call.
+
+   :param request: :class:`aiohttp.web.Request` object.
+
+   :return: :class:`str` :term:`userid` or ``None`` for not signed in users.
+
+
+.. coroutine:: permits(request, permission, context=None)
+
+   :param request: :class:`aiohttp.web.Request` object.
+
+   :return: ``True`` if registered user has requested *permission*,
+            ``False`` otherwise.
+
+
 .. function:: setup(app, identity_policy, autz_policy)
 
    Setup :mod:`aiohttp` application with security policies.