CDRIVER-3361 update documentation for owning return values (#863)

Author: eramongodb

src/libmongoc/doc/mongoc_session_opts_clone.rst

@@ -19,6 +19,11 @@ Parameters
 
 * ``opts``: A :symbol:`mongoc_session_opt_t`.
 
+Returns
+-------
+
+A new :symbol:`mongoc_session_opt_t` that must be freed with :symbol:`mongoc_session_opts_destroy()`.
+
 .. only:: html
 
   .. include:: includes/seealso/session.txt

src/libmongoc/doc/mongoc_session_opts_get_default_transaction_opts.rst

@@ -11,13 +11,20 @@ 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 returned value is valid only for the lifetime of ``opts``.  See :symbol:`mongoc_session_opts_set_default_transaction_opts()`.
+The default options for transactions started with this session.
 
 Parameters
 ----------
 
 * ``opts``: A :symbol:`mongoc_session_opt_t`.
 
+Returns
+-------
+
+A :symbol:`mongoc_transaction_opt_t` which should not be modified or freed.
+
+See :symbol:`mongoc_session_opts_set_default_transaction_opts()`.
+
 .. only:: html
 
   .. include:: includes/seealso/session.txt

src/libmongoc/doc/mongoc_session_opts_get_transaction_opts.rst

@@ -12,7 +12,9 @@ Synopsis
   mongoc_session_opts_get_transaction_opts (
      const mongoc_client_session_t *session) BSON_GNUC_WARN_UNUSED_RESULT;
 
-The options for the current transaction started with this session. The resulting :symbol:`mongoc_transaction_opt_t` should be freed with :symbol:`mongoc_transaction_opts_destroy`. If this ``session`` is not in a transaction, then the returned value is ``NULL``. See :symbol:`mongoc_client_session_in_transaction()`. 
+The options for the current transaction started with this session.
+
+If this ``session`` is not in a transaction, then the returned value is ``NULL``. See :symbol:`mongoc_client_session_in_transaction()`. 
 
 Parameters
 ----------
@@ -22,7 +24,7 @@ Parameters
 Returns
 -------
 
-A newly allocated :symbol:`mongoc_transaction_opt_t` that should be freed with :symbol:`mongoc_transaction_opts_destroy` or ``NULL`` if the session is not in a transaction.
+If the session is in a transaction, a new :symbol:`mongoc_transaction_opt_t` that must be freed with :symbol:`mongoc_transaction_opts_destroy()`. Otherwise, ``NULL``.
 
 .. only:: html
 

src/libmongoc/doc/mongoc_session_opts_new.rst

@@ -15,6 +15,11 @@ Synopsis
 
 See the example code for :symbol:`mongoc_session_opts_set_causal_consistency`.
 
+Returns
+-------
+
+A new :symbol:`mongoc_session_opt_t` that must be freed with :symbol:`mongoc_session_opts_destroy()`.
+
 .. only:: html
 
   .. include:: includes/seealso/session.txt

src/libmongoc/doc/mongoc_transaction_opts_clone.rst

@@ -19,6 +19,11 @@ Parameters
 
 * ``opts``: A :symbol:`mongoc_transaction_opt_t`.
 
+Returns
+-------
+
+A new :symbol:`mongoc_transaction_opt_t` that must be freed with :symbol:`mongoc_transaction_opts_destroy()`.
+
 .. only:: html
 
   .. include:: includes/seealso/session.txt

src/libmongoc/doc/mongoc_transaction_opts_new.rst

@@ -11,7 +11,12 @@ Synopsis
   mongoc_transaction_opt_t *
   mongoc_transaction_opts_new (void);
 
-Create a :symbol:`mongoc_transaction_opt_t` to configure multi-document transactions. The struct must be freed with :symbol:`mongoc_transaction_opts_destroy`.
+Create a :symbol:`mongoc_transaction_opt_t` to configure multi-document transactions.
+
+Returns
+-------
+
+A new :symbol:`mongoc_transaction_opt_t` that must be freed with :symbol:`mongoc_transaction_opts_destroy()`.
 
 .. only:: html