From 69b7314dc644c27289de76afc93684a98428ad05 Mon Sep 17 00:00:00 2001
From: Jeremy Mikola <jmikola@php.net>
Date: Mon, 11 Feb 2019 15:22:44 +0000
Subject: [PATCH] Clarify interactions with sessions and transactions

Copy some language from the MongoDB manual and clarify that sessions close due to garbage collection.


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@346802 c90b9560-bf6c-de11-be94-00142212c4b1
---
 .../mongodb/driver/session/aborttransaction.xml  |  6 +++---
 .../mongodb/driver/session/committransaction.xml |  5 +++--
 .../mongodb/driver/session/endsession.xml        | 10 ++++++++--
 .../mongodb/driver/session/starttransaction.xml  | 16 +++++++++-------
 4 files changed, 23 insertions(+), 14 deletions(-)

diff --git a/reference/mongodb/mongodb/driver/session/aborttransaction.xml b/reference/mongodb/mongodb/driver/session/aborttransaction.xml
index b0b4b0838e..2efa02bea0 100644
--- a/reference/mongodb/mongodb/driver/session/aborttransaction.xml
+++ b/reference/mongodb/mongodb/driver/session/aborttransaction.xml
@@ -14,9 +14,9 @@
    <void />
   </methodsynopsis>
   <para>
-   This method aborts an existing transaction and all the associated
-   operations are rolled back. It is like all operations that were part of
-   this transaction never existed.
+   Terminates the multi-document transaction and rolls back any data changes
+   made by the operations within the transaction. That is, the transaction ends
+   without saving any of the changes made by the operations in the transaction.
   </para>
  </refsect1>
 
diff --git a/reference/mongodb/mongodb/driver/session/committransaction.xml b/reference/mongodb/mongodb/driver/session/committransaction.xml
index 7ccaf4f789..7bfc4e2e7a 100644
--- a/reference/mongodb/mongodb/driver/session/committransaction.xml
+++ b/reference/mongodb/mongodb/driver/session/committransaction.xml
@@ -14,8 +14,9 @@
    <void />
   </methodsynopsis>
   <para>
-   This method commits an existing transaction and all the associated
-   operations are persisted in the database.
+   Saves the changes made by the operations in the multi-document transaction
+   and ends the transaction. Until the commit, none of the data changes made
+   from within the transaction are visible outside the transaction.
   </para>
  </refsect1>
 
diff --git a/reference/mongodb/mongodb/driver/session/endsession.xml b/reference/mongodb/mongodb/driver/session/endsession.xml
index 7860daf1f3..6027039b22 100644
--- a/reference/mongodb/mongodb/driver/session/endsession.xml
+++ b/reference/mongodb/mongodb/driver/session/endsession.xml
@@ -15,9 +15,15 @@
   </methodsynopsis>
   <para>
    This method closes an existing session. If a transaction was associated
-   with this session, this transaction is also aborted, and all its
-   operations are rolled back.
+   with this session, the transaction will be aborted. After calling this
+   method, applications should not invoke other methods on the session.
   </para>
+  <note>
+   <simpara>
+    Sessions are also closed during garbage collection. It should not be
+    necessary to call this method under normal circumstances.
+   </simpara>
+  </note>
  </refsect1>
 
  <refsect1 role="parameters">
diff --git a/reference/mongodb/mongodb/driver/session/starttransaction.xml b/reference/mongodb/mongodb/driver/session/starttransaction.xml
index 774c264531..9c89c071a0 100644
--- a/reference/mongodb/mongodb/driver/session/starttransaction.xml
+++ b/reference/mongodb/mongodb/driver/session/starttransaction.xml
@@ -14,19 +14,21 @@
    <methodparam><type>array|object</type><parameter>options</parameter></methodparam>
   </methodsynopsis>
   <para>
-   This method starts a new transaction within this session. When the session
-   is attached to operations through the <literal>"session"</literal>
-   argument, these operations become of the started transaction.
+   Starts a multi-document transaction associated with the session. At any given
+   time, you can have at most one open transaction for a session. After starting
+   a transaction, the session object must be passed to each operation via
+   the <literal>"session"</literal> option (e.g.
+   <methodname>MongoDB\Driver\Manager::executeBulkWrite</methodname>) in order
+   to associate that operation with the transaction.
   </para>
   <para>
    Transactions can be committed through
    <methodname>MongoDB\Driver\Session::commitTransaction</methodname>, and
    aborted with
    <methodname>MongoDB\Driver\Session::abortTransaction</methodname>.
-  </para>
-  <para>
-   Transactions are also automatically aborted when the session is terminated
-   through <methodname>MongoDB\Driver\Session::endSession</methodname>.
+   Transactions are also automatically aborted when the session is closed from
+   garbage collection or by explicitly calling
+   <methodname>MongoDB\Driver\Session::endSession</methodname>.
   </para>
  </refsect1>