diff --git a/td/telegram/Client.h b/td/telegram/Client.h
index cbe7f3d25..dd2e97588 100644
--- a/td/telegram/Client.h
+++ b/td/telegram/Client.h
@@ -25,7 +25,7 @@ namespace td {
  * this function must not be called simultaneously from two different threads. Also note that all updates and
  * responses to requests should be applied in the same order as they were received, to ensure consistency.
  * Given this information, it's advisable to call this function from a dedicated thread.
- * Some service TDLib requests can be executed synchronously from any thread by using the Client::execute method.
+ * Some service TDLib requests can be executed synchronously from any thread using the Client::execute method.
  *
  * General pattern of usage:
  * \code
@@ -134,13 +134,13 @@ class Client final {
 /**
  * The future native C++ interface for interaction with TDLib.
  *
- * The TDLib client instance is created using the ClientManager::create_client_id method, returning a client identifier.
- * Requests to a TDLib client instance can be sent using the ClientManager::send method from any thread.
- * New updates and responses to requests can be received using the ClientManager::receive method from any thread
- * after a first request is sent to the client instance. ClientManager::receive must not be called simultaneously from
+ * A TDLib client instance can be created through the method ClientManager::create_client_id.
+ * Requests can then be sent using the method ClientManager::send from any thread.
+ * New updates and responses to requests can be received using the method ClientManager::receive from any thread after
+ * the first request has been sent to the client instance. ClientManager::receive must not be called simultaneously from
  * two different threads. Also note that all updates and responses to requests should be applied in the same order as
  * they were received, to ensure consistency.
- * Some TDLib requests can be executed synchronously from any thread by using the ClientManager::execute method.
+ * Some TDLib requests can be executed synchronously from any thread using the method ClientManager::execute.
  *
  * General pattern of usage:
  * \code
@@ -159,8 +159,8 @@ class Client final {
  *     continue;
  *   }
  *
- *   if (response.id == 0) {
- *     // process response.object as an incoming update of type td_api::Update for the client response.client_id
+ *   if (response.request_id == 0) {
+ *     // process response.object as an incoming update of the type td_api::Update for the client response.client_id
  *   } else {
  *     // process response.object as an answer to a request response.request_id for the client response.client_id
  *   }
@@ -182,14 +182,14 @@ class ClientManager final {
   /**
    * Request identifier.
    * Responses to TDLib requests will have the same request id as the corresponding request.
-   * Updates from TDLib will have request id == 0, incoming requests are thus disallowed to have request id == 0.
+   * Updates from TDLib will have the request_id == 0, incoming requests are thus not allowed to have request_id == 0.
    */
   using RequestId = std::uint64_t;
 
   /**
    * Returns an opaque identifier of a new TDLib instance.
    * The TDLib instance will not send updates until the first request is sent to it.
-   * \return Opaque indentifier of a new TDLib instance.
+   * \return Opaque identifier of a new TDLib instance.
    */
   ClientId create_client_id();
 
@@ -206,7 +206,7 @@ class ClientManager final {
    */
   struct Response {
     /**
-     * TDLib client instance identifier, for which the response is received.
+     * TDLib client instance identifier, for which the response was received.
      */
     ClientId client_id;
 
@@ -222,24 +222,24 @@ class ClientManager final {
   };
 
   /**
-   * Receives incoming updates and request responses from TDLib. May be called from any thread, but must not be
+   * Receives incoming updates and responses to requests from TDLib. May be called from any thread, but must not be
    * called simultaneously from two different threads.
    * \param[in] timeout The maximum number of seconds allowed for this function to wait for new data.
-   * \return An incoming update or request response. The object returned in the response may be a nullptr
+   * \return An incoming update or response to a request. The object returned in the response may be a nullptr
    *         if the timeout expires.
    */
   Response receive(double timeout);
 
   /**
-   * Synchronously executes TDLib requests. Only a few requests can be executed synchronously.
-   * May be called from any thread.
+   * Synchronously executes a TDLib request.
+   * A request can be executed synchronously, only if it is documented with "Can be called synchronously".
    * \param[in] request Request to the TDLib.
    * \return The request response.
    */
   static td_api::object_ptr<td_api::Object> execute(td_api::object_ptr<td_api::Function> &&request);
 
   /**
-   * Destroys the client manager and all TDLib client instance managed by it.
+   * Destroys the client manager and all TDLib client instances managed by it.
    */
   ~ClientManager();
 
diff --git a/td/telegram/td_json_client.h b/td/telegram/td_json_client.h
index a5562dd20..34658e20c 100644
--- a/td/telegram/td_json_client.h
+++ b/td/telegram/td_json_client.h
@@ -97,18 +97,18 @@ TDJSON_EXPORT void td_json_client_destroy(void *client);
 /*
  * New TDLib JSON interface.
  *
- * The main TDLib interface is asynchronous. To match requests with a corresponding response a field "@extra" can
+ * The main TDLib interface is asynchronous. To match requests with a corresponding response, the field "@extra" can
  * be added to the request object. The corresponding response will have an "@extra" field with exactly the same value.
- * Each returned object will have an "@client_id" field, containing and identifier of the client for which
- * a response or an update is received.
+ * Each returned object will have an "@client_id" field, containing the identifier of the client for which
+ * a response or an update was received.
  *
  * A TDLib client instance can be created through td_create_client_id.
- * Requests then can be sent using td_send from any thread and the received client identifier.
- * New updates and request responses can be received through td_receive from any thread. This function
- * must not be called simultaneously from two different threads. Also note that all updates and request responses
- * must be applied in the order they were received to ensure consistency.
- * Some TDLib requests can be executed synchronously from any thread by using td_execute.
- * The TDLib client instances are destroyed automatically after they are closed.
+ * Requests can then be sent using td_send and the received client identifier.
+ * New updates and responses to requests can be received through td_receive from any thread after the first request
+ * has been sent to the client instance. This function must not be called simultaneously from two different threads.
+ * Also note that all updates and responses to requests must be applied in the order they were received for consistency.
+ * Some TDLib requests can be executed synchronously from any thread using td_execute.
+ * TDLib client instances are destroyed automatically after they are closed.
  *
  * General pattern of usage:
  * \code
@@ -119,7 +119,7 @@ TDJSON_EXPORT void td_json_client_destroy(void *client);
  * while (true) {
  *   const char *result = td_receive(WAIT_TIMEOUT);
  *   if (result) {
- *     // parse the result as JSON object and process it as an incoming update or an answer to a previously sent request
+ *     // parse the result as a JSON object and process it as an incoming update or the answer to a previously sent request
  *   }
  * }
  * \endcode
@@ -128,31 +128,29 @@ TDJSON_EXPORT void td_json_client_destroy(void *client);
 /**
  * Returns an opaque identifier of a new TDLib instance.
  * The TDLib instance will not send updates until the first request is sent to it.
- * \return Opaque indentifier of a new TDLib instance.
+ * \return Opaque identifier of a new TDLib instance.
  */
 TDJSON_EXPORT int td_create_client_id();
 
 /**
  * Sends request to the TDLib client. May be called from any thread.
- * \param[in] client_id The TDLib client identifier.
+ * \param[in] client_id TDLib client identifier.
  * \param[in] request JSON-serialized null-terminated request to TDLib.
  */
 TDJSON_EXPORT void td_send(int client_id, const char *request);
 
 /**
  * Receives incoming updates and request responses. Must not be called simultaneously from two different threads.
- * Returned pointer will be deallocated by TDLib during next call to td_receive or td_execute
- * in the same thread, so it can't be used after that.
+ * The returned pointer can be used until the next call to td_receive or td_execute, after which it will be deallocated by TDLib.
  * \param[in] timeout The maximum number of seconds allowed for this function to wait for new data.
  * \return JSON-serialized null-terminated incoming update or request response. May be NULL if the timeout expires.
  */
 TDJSON_EXPORT const char *td_receive(double timeout);
 
 /**
- * Synchronously executes TDLib request. May be called from any thread.
- * Only a few requests can be executed synchronously.
- * Returned pointer will be deallocated by TDLib during next call to td_receive or td_execute
- * in the same thread, so it can't be used after that.
+ * Synchronously executes a TDLib request.
+ * A request can be executed synchronously, only if it is documented with "Can be called synchronously".
+ * The returned pointer can be used until the next call to td_receive or td_execute, after which it will be deallocated by TDLib.
  * \param[in] request JSON-serialized null-terminated request to TDLib.
  * \return JSON-serialized null-terminated request response.
  */