update documentation

doc/design/cluster_train/pserver_client.md

@@ -21,32 +21,23 @@ typedef struct {
 
 typedef struct paddle_pserver_client paddle_pserver_client;
 
-/**
- * @brief paddle_new_pserver_client creates a new parameter server
- * client.
- */
 paddle_pserver_client* paddle_new_pserver_client();
-
-/**
- * @brief paddle_pserver_client_release releases the parameter server
- * client.
- */
 void paddle_pserver_client_release(paddle_pserver_client* client);
 
 /**
- * @brief paddle_begin_init_params begins to initialize parameters
- * on parameter servers.
+ * @brief paddle_begin_init_params begins to initialize parameters on
+ * parameter servers.
  *
- * paddle_begin_init_params will be called from multiple trainers, only
- * one trainer will be selected to initialize the parameters on
+ * paddle_begin_init_params will be called from multiple trainers,
+ * only one trainer will be selected to initialize the parameters on
  * parameter servers. Other trainers will be blocked until the
  * initialization is done, and they need to get the initialized
  * parameters from parameter servers using @paddle_get_params.
  *
- * @param config_proto serialized parameter server configuration
- * protobuffer.
- * @return 1 if trainer is selected to initialize parameter servers,
- * otherwise 0.
+ * @param config_proto serialized parameter server configuration in
+ * Protocol Buffers format.
+ * @return 1 if the trainer is selected to initialize parameter
+ * servers, otherwise 0.
  */
 int paddle_begin_init_params(paddle_pserver_client* client, const char* config_proto);
 
@@ -55,10 +46,10 @@ int paddle_begin_init_params(paddle_pserver_client* client, const char* config_p
  * servers.
  *
  * @param param the parameter to initialize.
- * @return 0 if successful, otherwise -1. On failure the trainer need
- * to restart the entire initialization process starting from
- * paddle_begin_init_param. Or simply exit the program and wait for
- * cluster management system to restart trainer.
+ * @return 0 if successful, otherwise -1. On failure, the trainer need
+ * to restart the entire initialization process (starting
+ * from @paddle_begin_init_param). Or simply exit the program and wait
+ * for cluster management system to restart trainer.
  */
 int paddle_init_param(paddle_pserver_client* client, paddle_parameter params);
 
@@ -66,10 +57,10 @@ int paddle_init_param(paddle_pserver_client* client, paddle_parameter params);
  * @brief paddle_finish_init_params tells parameter servers client has
  * sent all parameters to parameter servers as initialization.
  *
- * @return 0 if successful, otherwise -1. On failure the trainer need
- * to restart the entire initialization process starting from
- * paddle_begin_init_param. Or simply exit the program and wait for
- * cluster management system to restart trainer.
+ * @return 0 if successful, otherwise -1. On failure, the trainer need
+ * to restart the entire initialization process (starting
+ * from @paddle_begin_init_param). Or simply exit the program and wait
+ * for cluster management system to restart trainer.
  */
 int paddle_finish_init_params(paddle_pserver_client* client);