minor edits

README.rst

@@ -53,9 +53,9 @@ i.e. when you embed your app's info (private key) in publicly available code.
     events = await api.stream.get()
     friends = await api.friends.getOnline()
 
-Pass :code:`access_token` and :code:`uid`
+Use :code:`access_token` and :code:`uid`
 that were received after authorization. For more details, see
-`aiomailru Documentation <https://aiomailru.readthedocs.io/>`_.
+`authorization instruction <https://aiomailru.readthedocs.io/en/latest/authorization.html>`_.
 
 Server application
 ~~~~~~~~~~~~~~~~~~
@@ -75,9 +75,9 @@ Use :code:`ServerSession` when REST API is needed in:
     events = await api.stream.get()
     friends = await api.friends.getOnline()
 
-Pass :code:`access_token` that was received after authorization.
+Use :code:`access_token` that was received after authorization.
 For more details, see
-`aiomailru Documentation <https://aiomailru.readthedocs.io/>`_.
+`authorization instruction <https://aiomailru.readthedocs.io/en/latest/authorization.html>`_.
 
 Installation
 ------------

docs/source/authorization.rst

@@ -1,18 +1,14 @@
 Authorization
 =============
 
-To authorize with Mail.Ru OAuth 2.0 you need :code:`app_id`.
-And you need either :code:`private_key` or :code:`secret_key`
-for executing API requests after authorization.
-
 The preferred way to authorize is an :code:`async with` statement.
 After authorization the session will have the following attributes:
 
 * :code:`session_key` aka :code:`access_token`
-* :code:`uid` that is necessary only when :code:`secret_key` not passed
 * :code:`refresh_token`
 * :code:`expires_in`
 * :code:`token_type` if Implicit Grant used
+* :code:`uid`
 
 Authorization Code Grant
 ------------------------
@@ -22,8 +18,8 @@ Authorization Code Grant
     from aiomailru import CodeSession, API
 
     app_id = 123456
-    private_key = 'abcde'
-    secret_key = ''
+    private_key = ''
+    secret_key = 'xyz'
 
     async with CodeSession(app_id, private_key, secret_key, code, redirect_uri) as session:
         api = API(session)
@@ -42,8 +38,8 @@ Implicit Grant
     from aiomailru import ImplicitSession, API
 
     app_id = 123456
-    private_key = ''
-    secret_key = 'xyz'
+    private_key = 'abcde'
+    secret_key = ''
 
     async with ImplicitSession(app_id, private_key, secret_key, email, passwd, scope) as session:
         api = API(session)
@@ -62,7 +58,7 @@ Password Grant
 
     app_id = 123456
     private_key = 'abcde'
-    secret_key = 'xyz'
+    secret_key = ''
 
     async with PasswordSession(app_id, private_key, secret_key, email, passwd, scope) as session:
         api = API(session)
@@ -81,7 +77,7 @@ Refresh Token
 
     app_id = 123456
     private_key = ''
-    secret_key = ''
+    secret_key = 'xyz'
 
     async with RefreshSession(app_id, private_key, secret_key, refresh_token) as session:
         api = API(session)

docs/source/rest_api.rst

@@ -6,6 +6,10 @@ List of all methods is available here: https://api.mail.ru/docs/reference/rest/.
 Executing requests
 ------------------
 
+For executing API requests call an instance of :code:`APIMethod` class.
+You can get it as an attribute of :code:`API` class instance or
+as an attribute of other :code:`APIMethod` class instance.
+
 .. code-block:: python
 
     from aiomailru import API
@@ -15,16 +19,16 @@ Executing requests
     events = await api.stream.get()  # events for current user
     friends = await api.friends.get()  # current user's friends
 
-Under the hood each API request is enriched with parameters (https://api.mail.ru/docs/guides/restapi/#params):
+Under the hood each API request is enriched with parameters to generate signature:
+
+* :code:`method`
+* :code:`app_id`
+* :code:`session_key`
+* :code:`secure`
 
-* :code:`method`, required
-* :code:`app_id`, required
-* :code:`sig`, required (https://api.mail.ru/docs/guides/restapi/#sig)
-* :code:`session_key`, required
-* :code:`uid` if necessary
-* :code:`secure` if necessary
+and with the following parameter after generating signature:
 
-to `authorize request <https://api.mail.ru/docs/guides/restapi/#session>`_.
+* :code:`sig`, see https://api.mail.ru/docs/guides/restapi/#sig
 
 Objects
 -------