jsonrpc: Add function comments.

Signed-off-by: Ben Pfaff <blp@nicira.com>
Acked-by: Russell Bryant <rbryant@redhat.com>

lib/jsonrpc.c

@@ -1063,43 +1063,57 @@ jsonrpc_session_recv_wait(struct jsonrpc_session *s)
     }
 }
 
+/* Returns true if 's' is currently connected or trying to connect. */
 bool
 jsonrpc_session_is_alive(const struct jsonrpc_session *s)
 {
     return s->rpc || s->stream || reconnect_get_max_tries(s->reconnect);
 }
 
+/* Returns true if 's' is currently connected. */
 bool
 jsonrpc_session_is_connected(const struct jsonrpc_session *s)
 {
     return s->rpc != NULL;
 }
 
+/* Returns a sequence number for 's'.  The sequence number increments every
+ * time 's' connects or disconnects.  Thus, a caller can use the change (or
+ * lack of change) in the sequence number to figure out whether the underlying
+ * connection is the same as before. */
 unsigned int
 jsonrpc_session_get_seqno(const struct jsonrpc_session *s)
 {
     return s->seqno;
 }
 
+/* Returns the current status of 's'.  If 's' is NULL or is disconnected, this
+ * is 0, otherwise it is the status of the connection, as reported by
+ * jsonrpc_get_status(). */
 int
 jsonrpc_session_get_status(const struct jsonrpc_session *s)
 {
     return s && s->rpc ? jsonrpc_get_status(s->rpc) : 0;
 }
 
+/* Returns the last error reported on a connection by 's'.  The return value is
+ * 0 only if no connection made by 's' has ever encountered an error.  See
+ * jsonrpc_get_status() for return value interpretation. */
 int
 jsonrpc_session_get_last_error(const struct jsonrpc_session *s)
 {
     return s->last_error;
 }
 
+/* Populates 'stats' with statistics from 's'. */
 void
 jsonrpc_session_get_reconnect_stats(const struct jsonrpc_session *s,
                                     struct reconnect_stats *stats)
 {
     reconnect_get_stats(s->reconnect, time_msec(), stats);
 }
 
+/* Enables 's' to reconnect to the peer if the connection drops. */
 void
 jsonrpc_session_enable_reconnect(struct jsonrpc_session *s)
 {
@@ -1108,28 +1122,39 @@ jsonrpc_session_enable_reconnect(struct jsonrpc_session *s)
                           RECONNECT_DEFAULT_MAX_BACKOFF);
 }
 
+/* Forces 's' to drop its connection (if any) and reconnect. */
 void
 jsonrpc_session_force_reconnect(struct jsonrpc_session *s)
 {
     reconnect_force_reconnect(s->reconnect, time_msec());
 }
 
+/* Sets 'max_backoff' as the maximum time, in milliseconds, to wait after a
+ * connection attempt fails before attempting to connect again. */
 void
 jsonrpc_session_set_max_backoff(struct jsonrpc_session *s, int max_backoff)
 {
     reconnect_set_backoff(s->reconnect, 0, max_backoff);
 }
 
+/* Sets the "probe interval" for 's' to 'probe_interval', in milliseconds.  If
+ * this is zero, it disables the connection keepalive feature.  Otherwise, if
+ * 's' is idle for 'probe_interval' milliseconds then 's' will send an echo
+ * request and, if no reply is received within an additional 'probe_interval'
+ * milliseconds, close the connection (then reconnect, if that feature is
+ * enabled). */
 void
 jsonrpc_session_set_probe_interval(struct jsonrpc_session *s,
                                    int probe_interval)
 {
     reconnect_set_probe_interval(s->reconnect, probe_interval);
 }
 
+/* Sets the DSCP value used for 's''s connection to 'dscp'.  If this is
+ * different from the DSCP value currently in use then the connection is closed
+ * and reconnected. */
 void
-jsonrpc_session_set_dscp(struct jsonrpc_session *s,
-                         uint8_t dscp)
+jsonrpc_session_set_dscp(struct jsonrpc_session *s, uint8_t dscp)
 {
     if (s->dscp != dscp) {
         pstream_close(s->pstream);