fixes

Author: Chris Cho

docs/eloquent-models/relationships.txt

@@ -15,7 +15,7 @@ Overview
 --------
 
 This page describes the following Laravel Eloquent and MongoDB-specific
-relationships available in {+odm-short+} and shows examples on how to define
+relationships available in {+odm-short+} and shows examples of how to define
 and use them:
 
 - :ref:`One to one relationship <laravel-eloquent-relationship-one-to-one>`,
@@ -27,25 +27,23 @@ and use them:
 - :ref:`Embedded document pattern <laravel-embedded-document-pattern>`, a
   MongoDB-specific relationship that can represent a one to one or one to many
   relationship, created by using the ``embedsOne()`` or ``embedsMany()`` method
-- :ref:`Cross-database Relationships <laravel-relationship-cross-database>`,
-  required when you want to define
-  relationships between MongoDB and SQL models.
+- :ref:`Cross-database relationships <laravel-relationship-cross-database>`,
+  required when you want to create relationships between MongoDB and SQL models
 
-To establish a relationship, add a function to the model class that calls
-the appropriate relationship method. This function allows you to access the
-related model as a **dynamic property**. A dynamic property lets you access
-the related model by using the same syntax as you use to access a property
-on the model.
+Add a function to the model class that calls the appropriate relationship method
+to establish a relationship. This function allows you to access the related
+model as a **dynamic property**. A dynamic property lets you access the
+related model by using the same syntax as you use to access a property on the
+model.
 
 .. _laravel-eloquent-relationship-one-to-one:
 
 One to One Relationship
 -----------------------
 
-A one to one relationship between models consists of a model record that
-is related to exactly one other type of model record. In MongoDB, a record
-is represented as a document and different model types exist in separate
-collections.
+A one to one relationship between models consists of a model record related to
+exactly one other type of model record. In MongoDB, a record is represented as
+a document, and different model types exist in separate collections.
 
 When you add a one to one relationship by using the method, Eloquent lets you
 access the model by using a dynamic property and stores the model's document
@@ -58,9 +56,6 @@ When you add the inverse of the relationship by using the ``belongsTo()``
 method, Eloquent lets you access the model by using a dynamic property, but
 does not add any fields.
 
-The following section shows an example of how to create a one to one
-relationship.
-
 To learn more about one to one relationships, see
 `One to One <https://laravel.com/docs/{+laravel-docs-version+}/eloquent-relationships#one-to-one>`__
 in the Laravel docs.
@@ -83,8 +78,8 @@ as shown in the following example class:
    :language: php
    :dedent:
 
-The following sample code shows how you can instantiate a model for each class
-and add the relationship between them. Click the :guilabel:`Output` button to
+The following sample code shows how to instantiate a model for each class
+and add the relationship between them. Click the :guilabel:`View Output` button to
 see sample MongoDB documents created by running the code:
 
 .. io-code-block::
@@ -116,7 +111,7 @@ see sample MongoDB documents created by running the code:
         // ...
       }
 
-The following sample code shows how you can access the related models by using
+The following sample code shows how to access the related models by using
 the dynamic properties as defined in the example classes:
 
 .. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php
@@ -131,23 +126,20 @@ One to Many Relationship
 ------------------------
 
 A one to many relationship between models consists of a model that is
-the parent and one or more related model records which are the children.
+the parent and one or more related child model records.
 
 When you add a one to many relationship method, Eloquent lets you access the
 model by using a dynamic property and stores the parent model's document ID
 on each of the child model documents.
 
 In {+odm-short+}, you can define a one to many relationship by using the
-``hasMany()`` method on the parent class and optionally the ``belongsTo()``
+``hasMany()`` method on the parent class and, optionally, the ``belongsTo()``
 method on the child class.
 
 When you add the inverse of the relationship by using the ``belongsTo()``
 method, Eloquent lets you access the parent model by using a dynamic property
 without adding any fields.
 
-The following section shows an example of how to create a one to many
-relationship.
-
 To learn more about one to many relationships, see
 `One to Many <https://laravel.com/docs/{+laravel-docs-version+}/eloquent-relationships#one-to-many>`__
 in the Laravel docs.
@@ -163,15 +155,15 @@ relationship between a ``Planet`` parent model and ``Moon`` child model.
    :dedent:
 
 To define the inverse of the relationship on ``Moon``, add the dynamic
-property and call the ``belongsTo()`` method on it as shown in the following
+property and call the ``belongsTo()`` method on it, as shown in the following
 example class:
 
 .. literalinclude:: /includes/eloquent-models/relationships/MoonOneToMany.php
    :language: php
    :dedent:
 
-The following sample code shows how you can instantiate a model for each class
-and add the relationship between them.  Click the :guilabel:`Output` button to
+The following sample code shows how ton instantiate a model for each class
+and add the relationship between them.  Click the :guilabel:`View Output` button to
 see sample MongoDB documents created by running the code:
 
 .. io-code-block::
@@ -212,7 +204,7 @@ see sample MongoDB documents created by running the code:
         }
       ]
 
-The following sample code shows how you can access the related models by using
+The following sample code shows how to access the related models by using
 the dynamic properties as defined in the example classes.
 
 .. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php
@@ -236,22 +228,22 @@ In {+odm-short+}, you can define a many to many relationship by adding the
 
 When you define a many to many relationship in a relational database, Laravel
 creates a pivot table to track the relationships. When you use {+odm-short+},
-it omits the pivot table creation and instead adds the related document IDs
-to a document field, derived from the related model class name.
+it omits the pivot table creation and adds the related document IDs to a
+document field, derived from the related model class name.
 
 .. tip::
 
    Since {+odm-short+} uses a document field instead of a pivot table, omit
    the pivot table parameter from the ``belongsToMany()`` constructor or set
    it to ``null``.
 
-The following section shows an example of how to create a many to many
-relationship between model classes.
-
 To learn more about many to many relationships in Laravel, see
 `Many to Many <https://laravel.com/docs/{+laravel-docs-version+}/eloquent-relationships#many-to-many>`__
 in the Laravel docs.
 
+The following section shows an example of how to create a many to many
+relationship between model classes.
+
 Many to Many Example
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -269,8 +261,8 @@ relationship with ``Planet`` as shown in the following example class:
    :language: php
    :dedent:
 
-The following sample code shows how you can instantiate a model for each class
-and add the relationship between them. Click the :guilabel:`Output` button to
+The following sample code shows how to instantiate a model for each class
+and add the relationship between them. Click the :guilabel:`View Output` button to
 see sample MongoDB documents created by running the code:
 
 .. io-code-block::
@@ -338,7 +330,7 @@ see sample MongoDB documents created by running the code:
         }
       ]
 
-The following sample code shows how you can access the related models by using
+The following sample code shows how to access the related models by using
 the dynamic properties as defined in the example classes.
 
 .. literalinclude:: /includes/eloquent-models/relationships/RelationshipController.php
@@ -357,8 +349,9 @@ In MongoDB, the embedded document pattern adds the related model's data into
 the parent model instead of keeping foreign key references. This pattern
 when you must optimize for one or more of the following requirements:
 
-- Keep related data together in a single collection
-- Perform atomic updates on multiple fields of the document and the related data
+- Keep associated data together in a single collection
+- Perform atomic updates on multiple fields of the document and the associated
+  data
 - Reduce the number of reads required to fetch the data
 
 In {+odm-short+}, you can define embedded documents by using one of the
@@ -372,15 +365,15 @@ following dynamic property methods:
    These methods return Eloquent collections, which differ from query builder
    objects.
 
-The following section shows an example of how to use the embedded document
-pattern.
-
 To learn more about the MongoDB embedded document pattern, see the following
 MongoDB server tutorials:
 
 - :manual:`Model One-to-One Relationships with Embedded Documents </tutorial/model-embedded-one-to-one-relationships-between-documents/>`
 - :manual:`Model One-to-Many Relationships with Embedded Documents </tutorial/model-embedded-one-to-many-relationships-between-documents/>`
 
+The following section shows an example of how to use the embedded document
+pattern.
+
 Embedded Document Example
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -398,9 +391,9 @@ following example class:
    :language: php
    :dedent:
 
-The following sample code shows how you can create a ``SpaceShip`` model and
+The following sample code shows how to create a ``SpaceShip`` model and
 embed multiple ``Cargo`` models and the MongoDB document created by running the
-code. Click the :guilabel:`Output` button to see sample MongoDB documents
+code. Click the :guilabel:`View Output` button to see sample MongoDB documents
 created by running the code:
 
 .. io-code-block::
@@ -478,9 +471,9 @@ The ``Passenger`` model defines a ``BelongsToMany`` relationship with
    :language: php
    :dedent:
 
-The following sample code shows how you can create a ``SpaceShip`` model in
+The following sample code shows how to create a ``SpaceShip`` model in
 a MySQL database and related ``Passenger`` models in a MongoDB database and
-the data created by running the code. Click the :guilabel:`Output` button to
+the data created by running the code. Click the :guilabel:`View Output` button to
 see sample MongoDB documents created by running the code:
 
 .. io-code-block::
@@ -495,9 +488,27 @@ see sample MongoDB documents created by running the code:
       :language: none
       :visible: false
 
+      -- Row in the "space_ships" table
       +------+----------+
       | id   | name     |
       +------+----------+
       | 1234 | Nostromo |
       +------+----------+
 
+
+      // Document in the "passengers" collection
+      [
+        {
+          _id: ObjectId('65e625e74903fd63af0a5524'),
+          name: 'Ellen Ripley',
+          space_ship_id: 1234,
+          // ...
+        },
+        {
+          _id: ObjectId('65e625e74903fd63af0a5525'),
+          name: 'Dwayne Hicks',
+          space_ship_id: 1234,
+          // ...
+        }
+      ]
+