From c379fb4beb52cc1392faa685c12f0a78a5a0e007 Mon Sep 17 00:00:00 2001
From: Andrew Svetlov <andrew.svetlov@gmail.com>
Date: Wed, 18 Nov 2015 12:07:42 +0200
Subject: [PATCH] Improve doc

---
 docs/usage.rst | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/docs/usage.rst b/docs/usage.rst
index 274ead7..62d9ccf 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -9,7 +9,15 @@
 .. highlight:: python
 
 The library is build on top of two policies: :term:`authentication`
-and :term:`authorization`.
+and :term:`authorization` and public API.
+
+API is policy agnostic, all client code should not call policy code
+directly but use API only.
+
+Via API application can remember/forget user in local session
+(:func:`remember`/:func:`forget`), retrieve :term:`userid`
+(:func:`authorized_userid`) and check :term:`permission` for
+remembered user (:func:`permits`).
 
 
 Authentication
@@ -21,7 +29,7 @@ Actions related to retrieving, storing and removing user's
 Authenticated user has no access rights, the system even has no
 knowledge is there the user still registered in DB.
 
-If :term:`request` has an :term:`identity` it means the user has
+If :class:`aiohttp.web.Request` has an :term:`identity` it means the user has
 some ID that should be checked by :term:`authorization` policy.
 
 
@@ -32,4 +40,3 @@ some ID that should be checked by :term:`authorization` policy.
 identity is a string shared between browser and server.
 Thus it's not supposed to be database primary key, user login/email etc.
 Random string like uuid or hash is better choice.
-