client_common: Improve documentation of client_{pre,post}_select().

It was outdated and not worded very well. In particular, it referred
to a task pointer although the argument is named "context". Also,
client_open() does not return a "client data structure", so talk
about the effect of that function rather than its return value.

diff --git a/client_common.c b/client_common.c
index dc24a6280acc068bd2cb7cbc0fb178bd8586ca54..c25da96b169126ab36f5b6e7f95a2161d19a3aa9 100644 (file)
--- a/client_common.c
+++ b/client_common.c
@@ -50,13 +50,12 @@ void client_close(struct client_task *ct)
 }
 
 /*
- * The preselect hook for server commands.
+ * This function asks the scheduler to monitor a file descriptor which
+ * corresponds to an active connection. The descriptor is monitored for either
+ * reading or writing, depending on the state of the connection.
  *
- * The task pointer must contain a pointer to the initialized client data
- * structure as it is returned by client_open().
- *
- * This function checks the state of the connection and adds the file descriptor
- * of the connection to the read or write fd set of s accordingly.
+ * The context pointer is assumed to refer to a client task structure that was
+ * initialized earlier by client_open().
  */
 static void client_pre_select(struct sched *s, void *context)
 {
@@ -260,12 +259,15 @@ static int send_sb_command(struct client_task *ct)
 }
 
 /*
- * The post select hook for client commands.
+ * This function reads or writes to the socket file descriptor which
+ * corresponds to an established connection between the client and the server.
+ * It depends on the current state of the connection and on the readiness of
+ * the socket file descriptor which type of I/O is going to be performed.
+ * Besides the initial handshake and authentication, the function sends the
+ * server command and receives the output from the server, if any.
  *
- * Depending on the current state of the connection and the status of the read
- * and write fd sets of s, this function performs the necessary steps to
- * authenticate the connection, to send the command given by t->private_data
- * and to receive para_server's output, if any.
+ * The context pointer refers to a client task structure that was initialized
+ * earlier by client_open().
  */
 static int client_post_select(struct sched *s, void *context)
 {