DOCS-954 eval() helper and nolock

source/includes/fact-eval-lock.rst

@@ -0,0 +1,19 @@
+.. eval-command-nolock
+
+By default, :dbcommand:`eval` takes a global write lock before
+evaluating the JavaScript function. This means that :dbcommand:`eval`
+blocks all other read and write operations to the database while the
+:dbcommand:`eval` operation runs. Set ``nolock`` to ``true`` to ensure
+that :dbcommand:`eval` does not take this global write lock before
+evaluating the function. The flag does not impact whether the
+JavaScript code itself takes a write lock.
+
+.. eval-method-lock
+
+The :method:`db.eval()` method takes a global write lock by default
+before executing the JavaScript function. This means that
+:method:`db.eval()` blocks all other read and write operations to the
+database while the :method:`db.eval()` operation runs. You can,
+however, use the :dbcommand:`eval` command, instead of the
+:method:`db.eval()` method, with the ``nolock`` flag to ``true``. See
+:dbcommand:`eval` command for more details.

source/reference/command/eval.txt

@@ -22,7 +22,7 @@ eval
 
    The command contains the following fields:
 
-   :param JavaScript function:
+   :field JavaScript function:
 
       A JavaScript function.
 
@@ -43,7 +43,7 @@ eval
             // ...
          }
 
-   :param arguments:
+   :field arguments:
 
       A list of arguments to pass to the JavaScript ``function`` if
       the function accepts arguments. Omit if the ``function`` does
@@ -54,19 +54,10 @@ eval
       An array of corresponding arguments to the ``function``. Omit
       ``args`` if the ``function`` does not take arguments.
 
-   :field boolean nolock:
+   :field boolean nolock: Optional.
 
-      Optional. Specifies whether to disable the write lock. By
-      default, :dbcommand:`eval` takes a write lock. There are
-      circumstances where the :dbcommand:`eval` executes a strictly
-      read-only operation that does not need to block other
-      operations. If ``nolock`` is ``true``, the
-      :dbcommand:`eval` does not take a write lock.
-
-      .. warning::
-
-         Do not disable the write lock if the function may modify
-         the contents of the database in any way.
+      .. include:: /includes/fact-eval-lock.rst
+         :end-before: eval-method-lock
 
    Consider the following example which uses :dbcommand:`eval` to
    perform an increment and calculate the average on the server:
@@ -111,8 +102,8 @@ eval
                },
                "eliot", 5 );
 
-   You cannot pass the ``nolock`` flag to the :method:`db.eval()`
-   in the :program:`mongo` shell.
+   The :method:`db.eval()` method does not support the ``nolock``
+   option.
 
    If you want to use the server's interpreter, you must run
    :dbcommand:`eval`. Otherwise, the :program:`mongo` shell's
@@ -144,15 +135,13 @@ eval
 
    .. warning::
 
-      - The :method:`db.eval()` operation takes a write lock by
-        default. This means that :dbcommand:`eval` blocks all other
-        read and write operations to the database while the
-        :dbcommand:`eval` operation runs. You can, however, disable
-        the lock by setting the ``nolock`` flag to ``true`` if the
-        :dbcommand:`eval` performs a strictly read-only operation.
+      - .. include:: /includes/fact-eval-lock.rst
+           :end-before: eval-method-lock
 
       - :dbcommand:`eval` also takes a JavaScript lock.
 
+.. modified in 2.4 version, the JavaScript lock is up to and including version 2.2
+
       - Do not use :dbcommand:`eval` for long running operations as
         :dbcommand:`eval` blocks all other operations. Consider using
         :doc:`other server side code execution options

source/reference/method/db.eval.txt

@@ -11,7 +11,9 @@ db.eval()
 
    The :method:`db.eval()` provides the ability to run JavaScript code
    on the MongoDB server. It is a :program:`mongo` shell wrapper around
-   the :dbcommand:`eval` command.
+   the :dbcommand:`eval` command. However, unlike the :dbcommand:`eval`
+   command, the :method:`db.eval()` method does not support the
+   ``nolock`` option.
 
    The method accepts the following parameters:
 
@@ -91,17 +93,12 @@ db.eval()
 
    .. warning::
 
-      - The :method:`db.eval()` operation takes a write lock by
-        default.  This means that :method:`db.eval()` blocks all other
-        read and write operations to the database while
-        the :method:`db.eval()` operation runs. However, if you are using the
-        :dbcommand:`eval` command using :method:`db.runCommand()`
-        rather than the helper, you can disable the lock by setting
-        the ``nolock`` flag to ``true`` if the :dbcommand:`eval`
-        performs a strictly read-only operation.
-
-      - :method:`db.eval()` also takes a JavaScript lock which blocks
-        all
+      -  .. include:: /includes/fact-eval-lock.rst
+            :start-after: eval-method-lock
+
+      - :method:`db.eval()` also takes a JavaScript lock.
+
+.. modified in 2.4 version, the JavaScript lock is up to and including version 2.2
 
       - Do not use :method:`db.eval()` for long running operations, as
         :method:`db.eval()` blocks all other operations. Consider using