Fix CDRIVER3441 - document mongoc_handshake_data_append and alias as … (#852)

* Fix CDRIVER3441 - document mongoc_handshake_data_append and alias as mongoc_add_driver_info

I took a slightly different tack on this and made the older form an alias to the preferred,
newer one.

https://jira.mongodb.org/browse/CDRIVER-3441

Signed-off-by: Jesse Williamson <[email protected]>

* Add Sphinx documentation.

Signed-off-by: Jesse Williamson <[email protected]>

* Move inline documentation out of source.

Signed-off-by: Jesse Williamson <[email protected]>

* Add test showing that forwarding function can be called.

Signed-off-by: Jesse Williamson <[email protected]>

* Revert renaming and forwarding function.

Signed-off-by: Jesse Williamson <[email protected]>

* Update documentation: this is not deprecated, we will be offering an
alternative.

Signed-off-by: Jesse Williamson <[email protected]>

* Add mongoc_handshake_data_append into the TOC/document structure.

Signed-off-by: Jesse Williamson <[email protected]>

* Update mongoc_handshake_data_append documentation to more accurately describe
server monitoring and initiation. Some cosmetic adjustments.

Signed-off-by: Jesse Williamson <[email protected]>

* Update example responses to reflect current behavior.

Signed-off-by: Jesse Williamson <[email protected]>

Author: Jesse Williamson

src/libmongoc/doc/mongoc_client_t.rst

@@ -89,4 +89,6 @@ Example
     mongoc_client_start_session
     mongoc_client_watch
     mongoc_client_write_command_with_opts
+    mongoc_handshake_data_append
+    
 

src/libmongoc/doc/mongoc_handshake_data_append.rst

@@ -0,0 +1,84 @@
+:man_page: mongoc_handshake_data_append
+
+mongoc_handshake_data_append()
+==============================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+   bool
+   mongoc_handshake_data_append (const char *driver_name,
+                                 const char *driver_version,
+                                 const char *platform);
+
+Appends the given strings to the handshake data for the underlying C Driver.
+
+Description
+-----------
+
+This function is intended for use by drivers which wrap the C Driver.
+Calling this function will store the given strings as handshake data about
+the system and driver by appending them to the handshake data for the
+underlying C Driver. These values, along with other handshake data collected
+during mongoc_init will be sent to the server as part of the initial
+connection handshake in the "client" document. This function must not be
+called more than once, or after server monitoring begins. For a single-threaded 
+:symbol:`mongoc_client_t`, server monitoring begins on the first operation 
+requiring a server. For a :symbol:`mongoc_client_pool_t`, server monitoring 
+begins on the first call to `:symbol:`mongoc_client_pool_pop`.
+
+The passed in strings are copied, and don't have to remain valid after the
+call to :symbol:`mongoc_handshake_data_append`. The driver may store truncated
+versions of the passed in strings.
+
+.. note::
+  This function allocates memory, and therefore caution should be used when
+  using this in conjunction with :symbol:`bson_mem_set_vtable`. If this function is
+  called before :symbol:`bson_mem_set_vtable`, then :symbol:`bson_mem_restore_vtable` must be
+  called before calling :symbol:`mongoc_cleanup`. Failure to do so will result in
+  memory being freed by the wrong allocator.
+
+Parameters
+----------
+
+* ``driver_name``: An optional string storing the name of the wrapping driver
+* ``driver_version``: An optional string storing the version of the wrapping driver.
+* ``platform``: An optional string storing any information about the current platform, for example configure options or compile flags.
+
+Returns
+-------
+
+``true`` if the given fields are set successfully. Otherwise, it returns ``false`` and logs an error.
+
+The default handshake data the driver sends with "hello" looks something
+like:
+
+.. code-block:: c
+
+ client: {
+   driver: {
+     name: "mongoc",
+     version: "1.5.0"
+   },
+   os: {...},
+   platform: "CC=gcc CFLAGS=-Wall -pedantic"
+ }
+
+If we call
+:symbol:`mongoc_handshake_data_append` ("phongo", "1.1.8", "CC=clang / ")
+and it returns true, the driver sends handshake data like:
+
+.. code-block:: c
+
+ client: {
+   driver: {
+     name: "mongoc / phongo",
+     version: "1.5.0 / 1.1.8"
+   },
+   os: {...},
+   platform: "CC=clang / gcc CFLAGS=-Wall -pedantic"
+ }
+
+

src/libmongoc/src/mongoc/mongoc-handshake.c

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 MongoDB, Inc.
+ * Copyright 2016-present MongoDB, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/libmongoc/src/mongoc/mongoc-handshake.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 MongoDB, Inc.
+ * Copyright 2016-present MongoDB, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -28,64 +28,7 @@ BSON_BEGIN_DECLS
 
 #define MONGOC_HANDSHAKE_APPNAME_MAX 128
 
-/**
- * mongoc_handshake_data_append:
- *
- * This function is intended for use by drivers which wrap the C Driver.
- * Calling this function will store the given strings as handshake data about
- * the system and driver by appending them to the handshake data for the
- * underlying C Driver. These values, along with other handshake data collected
- * during mongoc_init will be sent to the server as part of the initial
- * connection handshake in the "client" document. This function cannot be
- * called more than once, or after a handshake has been initiated.
- *
- * The passed in strings are copied, and don't have to remain valid after the
- * call to mongoc_handshake_data_append(). The driver may store truncated
- * versions of the passed in strings.
- *
- * Note:
- *   This function allocates memory, and therefore caution should be used when
- *   using this in conjunction with bson_mem_set_vtable. If this function is
- *   called before bson_mem_set_vtable, then bson_mem_restore_vtable must be
- *   called before calling mongoc_cleanup. Failure to do so will result in
- *   memory being freed by the wrong allocator.
- *
- *
- * @driver_name: An optional string storing the name of the wrapping driver
- * @driver_version: An optional string storing the version of the wrapping
- * driver.
- * @platform: An optional string storing any information about the current
- *            platform, for example configure options or compile flags.
- *
- *
- * Returns true if the given fields are set successfully. Otherwise, it returns
- * false and logs an error.
- *
- * The default handshake data the driver sends with "hello" looks something
- * like:
- *  client: {
- *    driver: {
- *      name: "mongoc",
- *      version: "1.5.0"
- *    },
- *    os: {...},
- *    platform: "CC=gcc CFLAGS=-Wall -pedantic"
- *  }
- *
- * If we call
- *   mongoc_handshake_data_append ("phongo", "1.1.8", "CC=clang")
- * and it returns true, the driver sends handshake data like:
- *  client: {
- *    driver: {
- *      name: "mongoc / phongo",
- *      version: "1.5.0 / 1.1.8"
- *    },
- *    os: {...},
- *    platform: "CC=gcc CFLAGS=-Wall -pedantic / CC=clang"
- *  }
- *
- */
-MONGOC_EXPORT (bool)
+MONGOC_EXPORT (bool) 
 mongoc_handshake_data_append (const char *driver_name,
                               const char *driver_version,
                               const char *platform);

src/libmongoc/tests/test-mongoc-handshake.c

@@ -818,8 +818,7 @@ test_mongoc_handshake_race_condition (void)
          BSON_ASSERT (!COMMON_PREFIX (thread_create) (
             &threads[j], &handshake_append_worker, NULL));
       }
-
-      for (j = 0; j < 4; ++j) {
+for (j = 0; j < 4; ++j) {
          COMMON_PREFIX (thread_join) (threads[j]);
       }
    }