DOCS-800 added dot notation documentation

Author: kay-kim

source/applications/read.txt

@@ -124,9 +124,11 @@ Consider the following examples that illustrate the use of the
           }
        )
 
+  *Arrays*
+
   - The following operation returns all documents in the ``bios``
     collection where the array field ``contribs`` contains the element
-    ``UNIX``:
+    ``'UNIX'``:
 
     .. code-block:: javascript
 
@@ -135,11 +137,36 @@ Consider the following examples that illustrate the use of the
             contribs: 'UNIX'
           }
        )
+       
+  - The following operation returns all documents in the ``bios``
+    collection where ``awards`` array contains a subdocument element
+    that contains the ``award`` field equal to ``'Turing Award'`` and the
+    ``year`` field greater than 1980:
+
+    .. code-block:: javascript
+
+       db.bios.find(
+          {
+            awards: {
+                      $elemMatch: {
+                           award: 'Turing Award',
+                           year: { $gt: 1980 }
+                      }
+            }
+          }
+       )
+
+    For more examples on accessing arrays, see :ref:`query documents
+    for arrays <document-query-arrays>` and :ref:`read operations
+    <read-operations-dot-notation-arrays>`.
+
+  *Subdocuments*
 
   - The following operation returns all documents in the ``bios``
     collection where the subdocument ``name`` contains a field
-    ``first`` with the value ``Yukihiro`` and a field ``last`` with the
-    value ``Matsumoto``:
+    ``first`` with the value ``'Yukihiro'`` and a field ``last`` with
+    the value ``'Matsumoto'``; the query uses :term:`dot-notation` to
+    access fields in a subdocument:
 
     .. code-block:: javascript
 
@@ -151,8 +178,8 @@ Consider the following examples that illustrate the use of the
        )
 
     The query matches the document where the ``name`` field contains a
-    subdocument with the field ``first`` with the value ``Yukihiro``
-    and a field ``last`` with the value ``Matsumoto``. For instance,
+    subdocument with the field ``first`` with the value ``'Yukihiro'``
+    and a field ``last`` with the value ``'Matsumoto'``. For instance,
     the query would match documents with ``name`` fields that
     held either of the following values:
 
@@ -201,6 +228,12 @@ Consider the following examples that illustrate the use of the
          first: 'Yukihiro'
        }
 
+    For more examples on accessing subdocuments, see :ref:`query
+    documents for subdocuments <document-query-subdocuments>` and
+    :ref:`read operations <read-operations-dot-notation-subdocuments>`.
+
+  *Compound Query Criteria*
+  
   - The following operation returns all documents in the ``bios``
     collection where either the field ``first`` in the sub-document
     ``name`` starts with the letter ``G`` **or** where the field
@@ -230,24 +263,6 @@ Consider the following examples that illustrate the use of the
           }
        )
 
-  - The following operation returns all documents in the ``bios``
-    collection where ``awards`` array contains a subdocument element
-    that contains the ``award`` field equal to ``Turing Award`` and the
-    ``year`` field greater than 1980:
-
-    .. code-block:: javascript
-
-       db.bios.find(
-          {
-            awards: {
-                      $elemMatch: {
-                           award: 'Turing Award',
-                           year: { $gt: 1980 }
-                      }
-            }
-          }
-       )
-
 - If there is a ``<projection>`` argument, the :method:`find()
   <db.collection.find()>` method returns only those fields as specified
   in the ``<projection>`` argument to include or exclude:
@@ -282,7 +297,7 @@ Consider the following examples that illustrate the use of the
 
   - The following operation finds the documents in the ``bios``
     collection where the ``contribs`` field contains the element
-    ``OOP`` and returns all fields *except* the ``_id`` field, the
+    ``'OOP'`` and returns all fields *except* the ``_id`` field, the
     ``first`` field in the ``name`` subdocument, and the ``birth``
     field from the matching documents:
 

source/applications/update.txt

@@ -161,8 +161,8 @@ Consider the following examples that illustrate the use of the
   field:
 
   - The :method:`update() <db.collection.update()>` method can perform
-    the update using the position of the element. Arrays in MongoDB are
-    zero-based.
+    the update using the position of the element and
+    :term:`dot-notation`. Arrays in MongoDB are zero-based.
 
     The following operation queries the ``bios`` collection for
     the first document with ``_id`` field equal to ``1`` and updates the
@@ -196,8 +196,7 @@ Consider the following examples that illustrate the use of the
 
   - The :method:`update() <db.collection.update()>` method can perform
     the update of an array that contains subdocuments by using the
-    :operator:`$` positional operator and the :wiki:`dot notation
-    <Dot+Notation+(Reaching+into+Objects)>`.
+    :operator:`$` positional operator and the :term:`dot-notation`.
 
     The following operation queries the ``bios`` collection for the first
     document where the ``_id`` field equals ``6`` and the ``awards``

source/core/document.txt

@@ -79,7 +79,7 @@ The document contains the following fields:
 
 - ``_id`` that holds an *ObjectId*.
 
-- ``name`` that holds a *sub-document* that contains the fields
+- ``name`` that holds a *subdocument* that contains the fields
   ``first`` and ``last``.
 
 - ``birth`` and ``death``, which both have *Date* types.
@@ -246,6 +246,9 @@ Consider the following examples of query documents:
 
      { _id: 1, name: { first: 'John', last: 'Backus' } }
 
+  The ``name`` field must match the document exactly, including the
+  order of the fields.
+
 - The following document specifies the compound query criteria where
   ``_id`` is equal to ``1`` **or** the ``name`` field equals the
   document ``{ first: 'John', last: 'Backus' }``:
@@ -254,6 +257,79 @@ Consider the following examples of query documents:
 
      { $or: [ { _id: 1 }, { name: { first: 'John', last: 'Backus' } } ] }
 
+  The ``name`` field must match the document exactly, including the
+  order of the fields.
+
+.. _document-query-arrays:
+
+*Query Documents for Arrays*
+
+You can specify query criteria for arrays at the array level and, with
+:term:`dot-notation`, at the element level:
+
+- The following document specifies the query criteria where
+  ``contribs`` matches exactly the array ``[ 'Fortran', 'ALGOL',
+  'Backus-Naur Form', 'FP' ]``, including the order of the elements:
+
+  .. code-block:: javascript
+  
+     { contribs: [ 'Fortran', 'ALGOL', 'Backus-Naur Form', 'FP' ] }
+
+- The following document specifies the query criteria where the value
+  of ``contribs`` is an array that contains as one of its element
+  ``'ALGOL'``:
+
+  .. code-block:: javascript
+
+    { contribs: 'ALGOL' }
+
+- The following document specifies the query criteria where
+  ``contribs`` contains an element ``'ALGOL'`` in the second position.
+  Array indexes are zero-based:
+
+  .. code-block:: javascript
+
+     { 'contribs.1': 'ALGOL' }
+
+See :ref:`read operations <read-operations-dot-notation-arrays>` for more
+examples with arrays.
+
+.. _document-query-subdocuments:
+
+*Query Documents for Subdocuments*
+
+You can specify query criteria for subdocuments at the subdocument
+level and, with :term:`dot-notation`, at the field level:
+
+- The following document specifies the query criteria where the value
+  of the field ``name`` is a subdocument that contains *only* the field
+  ``first`` equal to ``'John'`` and the field ``last`` equal to
+  ``'Backus'``, in that order.
+
+  .. code-block:: javascript
+
+     { name: { first: 'John', last: 'Backus' } }
+
+- The following document specifies the query criteria where the value
+  of the field ``name`` is a subdocument that contains the field
+  ``first`` equal to ``'John'`` and may contain other fields:
+
+  .. code-block:: javascript
+
+     { 'name.first': 'John' }
+
+- The following document specifies the query criteria where the value
+  of the field ``awards`` is an array that contains, as one of its
+  elements, a subdocument that contains the field ``award`` equal to
+  ``'National Medal of Science'`` and may contain other fields:
+
+  .. code-block:: javascript
+
+     { 'awards.award': 'National Medal of Science' }
+
+See :ref:`read operations <read-operations-dot-notation-subdocuments>` for
+more examples with subdocuments.
+                
 When passed as an argument to methods such as the :method:`find()
 <db.collection.find()>` method, the :method:`remove()
 <db.collection.remove()>` method, or the :method:`update()
@@ -295,7 +371,8 @@ When passed as an argument to the :method:`update()
 
 - Modifies the field ``name`` whose value is another document.
   Specifically, the :operator:`$set` operator updates the ``middle``
-  field in the ``name`` subdocument.
+  field in the ``name`` subdocument. The document uses
+  :term:`dot-notation` to access a field in a subdocument.
 
 - Adds an element to the field ``awards`` whose value is an array.
   Specifically, the :operator:`$push` operator adds another document as
@@ -315,6 +392,10 @@ When passed as an argument to the :method:`update()
       }
    )
 
+For additional examples of updates that involve array elements,
+including where the elements are documents, see the :operator:`$`
+positional operator.
+
 .. _documents-index:
 .. _document-index-specification:
 
@@ -335,9 +416,10 @@ Index documents contain field and value pairs, in the following form:
 
 - ``value`` is either 1 for ascending or -1 for descending.
 
-The following document specifies the :ref:`multi-key index <index-type-multi-key>` on the ``_id``
-field and the ``last`` field contained in the subdocument ``name``
-field:
+The following document specifies the :ref:`multi-key index
+<index-type-multi-key>` on the ``_id`` field and the ``last`` field
+contained in the subdocument ``name`` field; the document uses
+:term:`dot-notation` to access a field in a subdocument:
 
 .. code-block:: javascript
 
@@ -355,7 +437,6 @@ the index to create:
    </core/read-operations>` and :doc:`write </core/write-operations>`
    operations.
 
-
 .. _documents-sort-order:
 
 Sort Order Specification Documents