improved comments on cluster node functions

Author: ajdavis

src/mongoc/mongoc-client.h

@@ -75,12 +75,15 @@ typedef struct _mongoc_client_t mongoc_client_t;
  * mongoc_stream_initiator_t:
  * @uri: The uri and options for the stream.
  * @host: The host and port (or UNIX domain socket path) to connect to.
+ * @user_data: The pointer passed to mongoc_client_set_stream_initiator.
  * @error: A location for an error.
  *
- * Creates a new mongoc_stream_t for the host and port. This can be used
- * by language bindings to create network transports other than those
- * built into libmongoc. An example of such would be the streams API
- * provided by PHP.
+ * Creates a new mongoc_stream_t for the host and port. Begin a
+ * non-blocking connect and return immediately.
+ *
+ * This can be used by language bindings to create network transports other
+ * than those built into libmongoc. An example of such would be the streams
+ * API provided by PHP.
  *
  * Returns: A newly allocated mongoc_stream_t or NULL on failure.
  */

src/mongoc/mongoc-topology-scanner.c

@@ -124,6 +124,7 @@ mongoc_topology_scanner_add_and_scan (mongoc_topology_scanner_t *ts,
 
    node = mongoc_topology_scanner_add (ts, host, id);
 
+   /* begin non-blocking connection, don't wait for success */
    if (node && mongoc_topology_scanner_node_setup (node, &node->last_error)) {
       node->cmd = mongoc_async_cmd (
          ts->async, node->stream, ts->setup,
@@ -276,6 +277,17 @@ mongoc_topology_scanner_ismaster_handler (mongoc_async_cmd_result_t async_status
                  node->ts->cb_data, error);
 }
 
+/*
+ *--------------------------------------------------------------------------
+ *
+ * mongoc_topology_scanner_node_connect_tcp --
+ *
+ *      Create a socket stream for this node, begin a non-blocking
+ *      connect and return.
+ *
+ *--------------------------------------------------------------------------
+ */
+
 static mongoc_stream_t *
 mongoc_topology_scanner_node_connect_tcp (mongoc_topology_scanner_node_t *node,
                                           bson_error_t                   *error)
@@ -404,6 +416,17 @@ mongoc_topology_scanner_node_connect_unix (mongoc_topology_scanner_node_t *node,
 #endif
 }
 
+
+/*
+ *--------------------------------------------------------------------------
+ *
+ * mongoc_topology_scanner_node_setup --
+ *
+ *      Create a stream and begin a non-blocking connect.
+ *
+ *--------------------------------------------------------------------------
+ */
+
 bool
 mongoc_topology_scanner_node_setup (mongoc_topology_scanner_node_t *node, bson_error_t *error)
 {