DOCS-954 eval() helper and nolock

DOCS-954 db.eval() method and nolock option

DOCS-954 incorporate Scott's feedback

incorporate Tad's comments

DOCS-954 eval and lock

Author: kay-kim

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
@@ -56,17 +56,11 @@ eval
 
    :field boolean nolock:
 
-      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.
+      Optional. By default, :dbcommand:`eval` takes a global write lock
+      before evaluating the JavaScript function. If ``nolock`` is
+      ``true``, the :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.
 
    Consider the following example which uses :dbcommand:`eval` to
    perform an increment and calculate the average on the server:
@@ -111,8 +105,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 +138,20 @@ 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.
+      - The :dbcommand:`eval` command takes a global write lock by
+        default before executing the JavaScript function. This means
+        that :dbcommand:`eval` blocks all other read and write
+        operations to the database while the :dbcommand:`eval`
+        operation runs. You can, however, set the ``nolock`` flag to
+        ``true`` to prevent the :dbcommand:`eval` command from taking a
+        global write lock before executing the JavaScript function. The
+        flag does not impact whether the JavaScript code itself takes
+        a write 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,18 @@ 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
+      - 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.
+
+      - :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