Documented custom exception behavior (addresses issue #2561). (#2595)

CHANGELOG

@@ -1,6 +1,8 @@
 devel
 -----
 
+* removed `exception` field from transaction error result; users should throw
+  explicit `Error` instances to return custom exceptions (addresses issue #2561)
 
 v3.2.beta1 (2017-06-12)
 -----------------------

Documentation/Books/Manual/Transactions/TransactionInvocation.md

@@ -231,6 +231,29 @@ db._executeTransaction({
 });
 ```
 
+### Custom exceptions
+
+One may wish to define custom exceptions inside of a transaction. To have the
+exception propagate upwards properly, please throw an an instance of base
+JavaScript `Error` class or a derivative. To specify an error number, include it
+as the `errorNumber` field. As an example:
+
+```js
+db._executeTransaction({
+  collections: {},
+  action: function () {
+    var err = new Error('My error context');
+    err.errorNumber = 1234;
+    throw err;
+  }
+});
+```
+
+**Note**: In previous versions, custom exceptions which did not have an
+`Error`-like form were simply converted to strings and exposed in the
+`exception` field of the returned error. This is no longer the case, as it had
+the potential to leak unwanted information if improperly used.
+
 ### Examples
 
 The first example will write 3 documents into a collection named *c1*.