CDRIVER-3362 update documentation for non-owning return values (#864)

Author: eramongodb

src/libmongoc/doc/mongoc_client_session_get_client.rst

@@ -11,13 +11,18 @@ Synopsis
   mongoc_client_t *
   mongoc_client_session_get_client (const mongoc_client_session_t *session);
 
-Returns the :symbol:`mongoc_client_t` from which this session was created with :symbol:`mongoc_client_start_session()`.
+Returns the :symbol:`mongoc_client_t` from which this session was created. See :symbol:`mongoc_client_start_session()`.
 
 Parameters
 ----------
 
 * ``session``: A :symbol:`mongoc_client_session_t`.
 
+Returns
+-------
+
+A :symbol:`mongoc_client_t` that should not be freed.
+
 .. only:: html
 
   .. include:: includes/seealso/session.txt

src/libmongoc/doc/mongoc_client_session_get_cluster_time.rst

@@ -11,7 +11,7 @@ Synopsis
   const bson_t *
   mongoc_client_session_get_cluster_time (const mongoc_client_session_t *session);
 
-Get the session's clusterTime, as a BSON document.
+Get the session's clusterTime as a BSON document.
 
 Parameters
 ----------
@@ -21,7 +21,7 @@ Parameters
 Returns
 -------
 
-A :symbol:`bson:bson_t` you must not modify or free. If the session has not been used for any operation and you have not called :symbol:`mongoc_client_session_advance_cluster_time`, then the returned value is NULL.
+If the session has not been used for any operation and :symbol:`mongoc_client_session_advance_cluster_time()` has not been called, a :symbol:`bson:bson_t` that is valid only for the lifetime of ``session``. Otherwise, ``NULL``.
 
 .. only:: html
 

src/libmongoc/doc/mongoc_client_session_get_lsid.rst

@@ -11,7 +11,7 @@ Synopsis
   const bson_t *
   mongoc_client_session_get_lsid (mongoc_client_session_t *session);
 
-Get the server-side "logical session ID" associated with this :symbol:`mongoc_client_session_t`, as a BSON document.
+Get the server-side "logical session ID" associated with this :symbol:`mongoc_client_session_t` as a BSON document.
 
 Parameters
 ----------
@@ -21,7 +21,7 @@ Parameters
 Returns
 -------
 
-A :symbol:`bson:bson_t` you must not modify or free.
+A :symbol:`bson:bson_t` that is valid only for the lifetime of ``session``.
 
 .. only:: html
 

src/libmongoc/doc/mongoc_client_session_get_opts.rst

@@ -21,7 +21,7 @@ Parameters
 Returns
 -------
 
-A :symbol:`mongoc_session_opt_t` you must not modify or free.
+A :symbol:`mongoc_session_opt_t` that is valid only for the lifetime of ``session``.
 
 .. only:: html
 

src/libmongoc/doc/mongoc_session_opts_get_default_transaction_opts.rst

@@ -11,7 +11,7 @@ Synopsis
   const mongoc_transaction_opt_t *
   mongoc_session_opts_get_default_transaction_opts (const mongoc_session_opt_t *opts);
 
-The default options for transactions started with this session.
+The default options for transactions started with this session. See :symbol:`mongoc_session_opts_set_default_transaction_opts()`.
 
 Parameters
 ----------
@@ -21,9 +21,7 @@ Parameters
 Returns
 -------
 
-A :symbol:`mongoc_transaction_opt_t` which should not be modified or freed.
-
-See :symbol:`mongoc_session_opts_set_default_transaction_opts()`.
+A :symbol:`mongoc_transaction_opt_t` that is valid only for the lifetime of ``opts``.
 
 .. only:: html
 

src/libmongoc/doc/mongoc_transaction_opts_get_read_concern.rst

@@ -11,13 +11,18 @@ Synopsis
   const mongoc_read_concern_t *
   mongoc_transaction_opts_get_read_concern (const mongoc_transaction_opt_t *opts);
 
-Return the transaction options' :symbol:`mongoc_read_concern_t`. The returned value is valid only for the lifetime of ``opts``. See :symbol:`mongoc_transaction_opts_set_read_concern()`.
+Return the transaction options' :symbol:`mongoc_read_concern_t`. See :symbol:`mongoc_transaction_opts_set_read_concern()`.
 
 Parameters
 ----------
 
 * ``opts``: A :symbol:`mongoc_transaction_opt_t`.
 
+Returns
+-------
+
+A :symbol:`mongoc_read_concern_t` that is valid only for the lifetime of ``opts``.
+
 .. only:: html
 
   .. include:: includes/seealso/session.txt

src/libmongoc/doc/mongoc_transaction_opts_get_read_prefs.rst

@@ -11,13 +11,18 @@ Synopsis
   const mongoc_read_prefs_t *
   mongoc_transaction_opts_get_read_prefs (const mongoc_transaction_opt_t *opts);
 
-Return the transaction options' :symbol:`mongoc_read_prefs_t`. The returned value is valid only for the lifetime of ``opts``. See :symbol:`mongoc_transaction_opts_set_read_prefs()`.
+Return the transaction options' :symbol:`mongoc_read_prefs_t`. See :symbol:`mongoc_transaction_opts_set_read_prefs()`.
 
 Parameters
 ----------
 
 * ``opts``: A :symbol:`mongoc_transaction_opt_t`.
 
+Returns
+-------
+
+A :symbol:`mongoc_read_prefs_t` that is valid only for the lifetime of ``opts``. 
+
 .. only:: html
 
   .. include:: includes/seealso/session.txt

src/libmongoc/doc/mongoc_transaction_opts_get_write_concern.rst

@@ -11,13 +11,18 @@ Synopsis
   const mongoc_write_concern_t *
   mongoc_transaction_opts_get_write_concern (const mongoc_transaction_opt_t *opts);
 
-Return the transaction options' :symbol:`mongoc_write_concern_t`. The returned value is valid only for the lifetime of ``opts``. See :symbol:`mongoc_transaction_opts_set_write_concern()`.
+Return the transaction options' :symbol:`mongoc_write_concern_t`. See :symbol:`mongoc_transaction_opts_set_write_concern()`.
 
 Parameters
 ----------
 
 * ``opts``: A :symbol:`mongoc_transaction_opt_t`.
 
+Returns
+-------
+
+A  :symbol:`mongoc_write_concern_t` that is valid only for the lifetime of ``opts``.
+
 .. only:: html
 
   .. include:: includes/seealso/session.txt