DOCS-1284 single source eval content; make explicit relationship btwn co...

source/includes/admonitions-eval.rst

@@ -0,0 +1,24 @@
+.. warning::
+
+   .. \|object| defined in included parameters-eval .. 
+   .. \|nolockobject| defined in included parameters-eval ..
+
+   - .. include:: /includes/fact-eval-lock.rst
+
+   - Do not use |object| for long running operations as
+     |object| blocks all other operations. Consider using
+     :doc:`other server side code execution options
+     </applications/server-side-javascript>`.
+
+   - You can not use |object| with :term:`sharded
+     <sharding>` data. In general, you should avoid using
+     |object| in :term:`sharded cluster`; nevertheless, it
+     is possible to use |object| with non-sharded
+     collections and databases stored in a :term:`sharded cluster`.
+
+   - .. include:: /includes/fact-eval-authentication.rst
+
+.. versionchanged:: 2.4
+   The V8 JavaScript engine, which became the default in 2.4, allows
+   multiple JavaScript operations to execute at the same time. Prior to
+   2.4, |object| executed in a single thread.

source/includes/examples-eval.rst

@@ -0,0 +1,38 @@
+.. eval-command-example
+
+.. code-block:: javascript
+
+   db.runCommand( {
+         eval: function(name, incAmount) {
+                  var doc = db.myCollection.findOne( { name : name } );
+
+                  doc = doc || { name : name , num : 0 , total : 0 , avg : 0 };
+
+                  doc.num++;
+                  doc.total += incAmount;
+                  doc.avg = doc.total / doc.num;
+
+                  db.myCollection.save( doc );
+                  return doc;
+               },
+         args: [ "eliot", 5 ]
+      }
+   );
+
+.. eval-method-example
+
+.. code-block:: javascript
+
+   db.eval( function(name, incAmount) {
+               var doc = db.myCollection.findOne( { name : name } );
+
+               doc = doc || { name : name , num : 0 , total : 0 , avg : 0 };
+
+               doc.num++;
+               doc.total += incAmount;
+               doc.avg = doc.total / doc.num;
+
+               db.myCollection.save( doc );
+               return doc;
+            },
+            "eliot", 5 );

source/includes/fact-eval-helper-method.rst

@@ -0,0 +1,5 @@
+The shell helper :method:`db.eval()` acts as a wrapper around the
+:dbcommand:`eval` command. As such, the helper method shares the
+characteristics and behavior of the underlying command itself with the
+*one exception* in that the :method:`db.eval()` method does not support
+the ``nolock`` option.

source/includes/parameters-eval.rst

@@ -0,0 +1,32 @@
+.. eval-param-function
+
+A JavaScript function.
+
+The function need not take any arguments, as in the first example,
+or may take arguments as in the second:
+
+.. code-block:: javascript
+
+   function () {
+     // ...
+   }
+
+.. code-block:: javascript
+
+   function (arg1, arg2) {
+      // ...
+   }
+
+.. eval-param-argument
+
+|list| of corresponding arguments to pass to the specified
+JavaScript function if the function accepts arguments. Omit if the
+function does not take arguments.
+
+.. eval-param-nolock
+
+Optional.
+
+.. |object| replace:: :dbcommand:`eval`
+.. |nolockobject| replace:: :dbcommand:`eval` command
+.. include:: /includes/fact-eval-lock.rst

source/reference/command/eval.txt

@@ -21,90 +21,39 @@ eval
       }
 
    The command contains the following fields:
-
-   :field JavaScript function:
-
-      A JavaScript function.
-
-      The function may accept no arguments, as in the following
-      example:
-
-      .. code-block:: javascript
-
-         function () {
-           // ...
-         }
-
-      The function can also accept arguments, as in the following example:
-
-      .. code-block:: javascript
-
-         function (arg1, arg2) {
-            // ...
-         }
-
-   :field arguments:
-
-      A list of arguments to pass to the JavaScript ``function`` if
-      the function accepts arguments. Omit if the ``function`` does
-      not take arguments.
+
+   :field function eval:
+      .. include:: /includes/parameters-eval.rst
+         :start-after: eval-param-function
+         :end-before: eval-param-argument
 
    :field array args:
 
-      An array of corresponding arguments to the ``function``. Omit
-      ``args`` if the ``function`` does not take arguments.
+      .. |list| replace:: An array
+      .. include:: /includes/parameters-eval.rst
+         :start-after: eval-param-argument
+         :end-before: eval-param-nolock
 
-   :field boolean nolock: Optional.
+   :field boolean nolock:
 
-      .. |object| replace:: :dbcommand:`eval`
-      .. |nolockobject| replace:: :dbcommand:`eval` command
-      .. include:: /includes/fact-eval-lock.rst
+      .. include:: /includes/parameters-eval.rst
+         :start-after: eval-param-nolock
 
    Consider the following example which uses :dbcommand:`eval` to
    perform an increment and calculate the average on the server:
 
-   .. code-block:: javascript
-
-      db.runCommand( {
-            eval: function(name, incAmount) {
-                     var doc = db.myCollection.findOne( { name : name } );
-
-                     doc = doc || { name : name , num : 0 , total : 0 , avg : 0 };
-
-                     doc.num++;
-                     doc.total += incAmount;
-                     doc.avg = doc.total / doc.num;
-
-                     db.myCollection.save( doc );
-                     return doc;
-                  },
-            args: [ "eliot", 5 ]
-         }
-      );
+      .. include:: /includes/examples-eval.rst
+         :start-after: eval-command-example
+         :end-before: .. eval-method-example
 
    The ``db`` in the function refers to the current database.
 
-   The shell also provides a helper method :method:`db.eval()`, so you
-   can express the above as follows:
-
-   .. code-block:: javascript
-
-      db.eval( function(name, incAmount) {
-                  var doc = db.myCollection.findOne( { name : name } );
-
-                  doc = doc || { name : name , num : 0 , total : 0 , avg : 0 };
-
-                  doc.num++;
-                  doc.total += incAmount;
-                  doc.avg = doc.total / doc.num;
-
-                  db.myCollection.save( doc );
-                  return doc;
-               },
-               "eliot", 5 );
+   The :program:`mongo` shell provides a helper method
+   :method:`db.eval()` [#eval-shell-helper]_, so you can express the
+   above as follows:
 
-   The :method:`db.eval()` method does not support the ``nolock``
-   option.
+   .. include:: /includes/examples-eval.rst
+      :start-after: .. eval-method-example
 
    If you want to use the server's interpreter, you must run
    :dbcommand:`eval`. Otherwise, the :program:`mongo` shell's
@@ -120,7 +69,7 @@ eval
       db.runCommand(
                      {
                        eval: function() { return x + x; },
-                       args: [3]
+                       args: [ 3 ]
                      }
                    )
 
@@ -129,35 +78,16 @@ eval
    .. code-block:: javascript
 
       {
-         "errno" : -3,
-         "errmsg" : "invoke failed: JS Error: ReferenceError: x is not defined nofile_b:1",
+         "errmsg" : "exception: JavaScript execution failed: ReferenceError: x is not defined near '{ return x + x; }' ",
+         "code" : 16722,
          "ok" : 0
       }
 
-   .. warning::
-
-      .. \|object| defined above .. 
-      .. \|nolockobject| defined above ..
-
-      - .. include:: /includes/fact-eval-lock.rst
-
-      - 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
-        </applications/server-side-javascript>`.
-
-      - You can not use :dbcommand:`eval` with :term:`sharded
-        <sharding>` data. In general, you should avoid using
-        :dbcommand:`eval` in :term:`sharded cluster`; nevertheless, it
-        is possible to use :dbcommand:`eval` with non-sharded
-        collections and databases stored in a :term:`sharded cluster`.
-
-      - .. include:: /includes/fact-eval-authentication.rst
-
-   .. versionchanged:: 2.4
-      The V8 JavaScript engine, which became the default in 2.4, allows
-      multiple JavaScript operations to execute at the same
-      time. Prior to 2.4, :dbcommand:`eval` executed in a single
-      thread.
+   .. \|object| defined in included parameters-eval .. 
+   .. \|nolockobject| defined in included parameters-eval ..
+   .. include:: /includes/admonitions-eval.rst
 
    .. seealso:: :doc:`/applications/server-side-javascript`
+
+   .. [#eval-shell-helper] 
+      .. include:: /includes/fact-eval-helper-method.rst

source/reference/method/db.eval.txt

@@ -10,59 +10,32 @@ db.eval()
 .. method:: db.eval(function, arguments)
 
    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. However, unlike the :dbcommand:`eval`
-   command, the :method:`db.eval()` method does not support the
-   ``nolock`` option.
+   on the MongoDB server.
+
+   .. include:: /includes/fact-eval-helper-method.rst
 
    The method accepts the following parameters:
 
    :param JavaScript function:
-
-      A JavaScript function.
-
-      The function need not take any arguments, as in the first
-      example, or may optionally take arguments as in the second:
-
-      .. code-block:: javascript
-
-         function () {
-           // ...
-         }
-
-      .. code-block:: javascript
-
-         function (arg1, arg2) {
-            // ...
-         }
+      .. include:: /includes/parameters-eval.rst
+         :start-after: eval-param-function
+         :end-before: eval-param-argument
 
    :param arguments:
 
-      A list of arguments to pass to the JavaScript ``function`` if
-      the function accepts arguments. Omit if the ``function`` does
-      not take arguments.
+      .. |list| replace:: A list
+      .. include:: /includes/parameters-eval.rst
+         :start-after: eval-param-argument
+         :end-before: eval-param-nolock
 
    Consider the following example of the :method:`db.eval()` method:
 
-   .. code-block:: javascript
-
-      db.eval( function(name, incAmount) {
-                  var doc = db.myCollection.findOne( { name : name } );
-
-                  doc = doc || { name : name , num : 0 , total : 0 , avg : 0 };
-
-                  doc.num++;
-                  doc.total += incAmount;
-                  doc.avg = doc.total / doc.num;
-
-                  db.myCollection.save( doc );
-                  return doc;
-               },
-               "<name>", 5 );
+   .. include:: /includes/examples-eval.rst
+      :start-after: .. eval-method-example
 
    - The ``db`` in the function refers to the current database.
 
-   - ``"<name>"`` is the argument passed to the function, and
+   - ``"eliot"`` is the argument passed to the function, and
      corresponds to the ``name`` argument.
 
    - ``5`` is an argument to the function and corresponds to the
@@ -86,37 +59,14 @@ db.eval()
    .. code-block:: javascript
 
       {
-         "errno" : -3,
-         "errmsg" : "invoke failed: JS Error: ReferenceError: x is not defined nofile_b:1",
+         "errmsg" : "exception: JavaScript execution failed: ReferenceError: x is not defined near '{ return x + x; }' ",
+         "code" : 16722,
          "ok" : 0
       }
 
-   .. warning::
-
-      .. |object| replace:: :method:`db.eval()`
-
-      .. |nolockobject| replace:: :dbcommand:`eval` *command*
-
-      - .. include:: /includes/fact-eval-lock.rst
-
-      - Do not use :method:`db.eval()` for long running operations, as
-        :method:`db.eval()` blocks all other operations. Consider using
-        :doc:`other server side code execution options
-        </applications/server-side-javascript>`.
-
-      - You can not use :method:`db.eval()` with :term:`sharded
-        <sharding>` data. In general, you should avoid using
-        :method:`db.eval()` in :term:`sharded cluster`; nevertheless,
-        it is possible to use :method:`db.eval()` with non-sharded
-        collections and databases stored in :term:`sharded cluster`.
-
-      - .. include:: /includes/fact-eval-authentication.rst
-
-   .. versionchanged:: 2.4
-      The V8 JavaScript engine, which became the default in 2.4, allows
-      multiple JavaScript operations to execute at the same
-      time. Prior to 2.4, :method:`db.eval()` executed in a single
-      thread.
+   .. |object| replace:: :method:`db.eval()`
+   .. |nolockobject| replace:: :dbcommand:`eval` *command*
+   .. include:: /includes/admonitions-eval.rst
 
    .. seealso::
 

source/reference/user-privileges.txt

@@ -272,7 +272,12 @@ roles. Consider the following:
    Requires :authrole:`clusterAdmin` and :authrole:`read` access to
    the :data:`config` database.
 
-:dbcommand:`applyOps`, :dbcommand:`eval`, and :method:`db.eval()`
+:dbcommand:`applyOps`, :dbcommand:`eval` [#eval-shell-helper]_
    Requires :authrole:`readAnyDatabase`, :authrole:`readWriteAnyDatabase`,
    :authrole:`userAdminAnyDatabase`, :authrole:`dbAdminAnyDatabase` and
    :authrole:`clusterAdmin` (on the ``admin`` database.)
+
+.. [#eval-shell-helper] The :program:`mongo` shell provides the shell
+   helper method :method:`db.eval()` for the :dbcommand:`eval` command.
+   As a wrapper, the method will require the same access requirements
+   as the command itself.