Work on documentation

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.