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

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>
 

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>
 

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">

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>