Merge pull request #786 from weaverryan/patch-1

Minor updates while reading the basic-mapping page

docs/en/reference/basic-mapping.rst

@@ -4,12 +4,12 @@ Basic Mapping
 This guide explains the basic mapping of entities and properties.
 After working through this guide you should know:
 
-- How to create PHP classes that can be saved in the database with Doctrine
+- How to create PHP objects that can be saved to the database with Doctrine;
 - How to configure the mapping between columns on tables and properties on
-  entities.
-- What Doctrine Mapping types are
-- Defining primary keys and how identifiers are generated by Doctrine
-- How quoting of reserved symbols works in Doctrine
+  entities;
+- What Doctrine mapping types are;
+- Defining primary keys and how identifiers are generated by Doctrine;
+- How quoting of reserved symbols works in Doctrine.
 
 Mapping of associations will be covered in the next chapter on
 :doc:`Association Mapping <association-mapping>`.
@@ -23,11 +23,11 @@ Doctrine.
 Creating Classes for the Database
 ---------------------------------
 
-Every PHP Class that you want to save in the database using Doctrine
-need to be marked as "Entity". The term "Entity" describes objects
-that have identity over many independent requests. This identity is
+Every PHP object that you want to save in the database using Doctrine
+is called an "Entity". The term "Entity" describes objects
+that have an identity over many independent requests. This identity is
 usually achieved by assigning a unique identifier to an entity.
-In this tutorial the following ``Message`` PHP class will serve as
+In this tutorial the following ``Message`` PHP class will serve as the
 example Entity:
 
 .. code-block:: php
@@ -40,14 +40,14 @@ example Entity:
         private $postedAt;
     }
 
-Because Doctrine is a generic library, it can only know about your
-entities when you are describing their existance and structure using
-Metadata Mapping, a pattern `described by Martin Fowler in PoEAA
-<http://martinfowler.com/eaaCatalog/metadataMapping.html>`_. Because
-of this pattern the documentation will often speak of "mapping something",
-which means that we use the metadata mapping pattern to use this feature.
+Because Doctrine is a generic library, it only knows about your
+entities because you will describe their existence and structure using
+mapping metadata, which is configuration that tells Doctrine how your
+entity should be stored in the database. The documentation will often
+speak of "mapping something", which means writing the mapping metadata
+that describes your entity.
 
-Doctrine provides several different ways for specifying object-relational
+Doctrine provides several different ways to specify object-relational
 mapping metadata:
 
 -  :doc:`Docblock Annotations <annotations-reference>`
@@ -55,9 +55,8 @@ mapping metadata:
 -  :doc:`YAML <yaml-mapping>`
 -  :doc:`PHP code <php-mapping>`
 
-This manual usually mentions docblock annotations in all the examples that are
-spread throughout all chapters, however for many examples alternative YAML and
-XML examples are given as well.
+This manual will usually show mapping metadata via docblock annotations, though
+many examples also show the equivalent configuration in YAML and XML.
 
 .. note::
 
@@ -65,10 +64,9 @@ XML examples are given as well.
     read from the source (annotations, xml or yaml) it is stored in an instance
     of the ``Doctrine\ORM\Mapping\ClassMetadata`` class and these instances are
     stored in the metadata cache.  If you're not using a metadata cache (not
-    recommended!) then the XML driver is the fastest by using PHP's native XML
-    support.
+    recommended!) then the XML driver is the fastest.
 
-Marking our ``Message`` entity for Doctrine is straightforward:
+Marking our ``Message`` class as an entity for Doctrine is straightforward:
 
 .. configuration-block::
 
@@ -95,7 +93,7 @@ Marking our ``Message`` entity for Doctrine is straightforward:
           type: entity
           # ...
 
-With no additional information given Doctrine expects the entity to be saved
+With no additional information, Doctrine expects the entity to be saved
 into a table with the same name as the class in our case ``Message``.
 You can change this by configuring information about the table:
 
@@ -133,12 +131,13 @@ Now the class ``Message`` will be saved and fetched from the table ``message``.
 Property Mapping
 ----------------
 
-The next step after defining a PHP class as entity is mapping of properties
+The next step after marking a PHP class as an entity is mapping its properties
 to columns in a table.
 
 To configure a property use the ``@Column`` docblock annotation. The ``type``
-attribute specifies the Doctrine Mapping Type to use for the field. If the type
-is not specified, ``string`` is used as the default mapping type.
+attribute specifies the :ref:`Doctrine Mapping Type <reference-mapping-types>`
+to use for the field. If the type is not specified, ``string`` is used as the
+default.
 
 .. configuration-block::
 
@@ -179,11 +178,12 @@ is not specified, ``string`` is used as the default mapping type.
               type: datetime
               name: posted_at
 
-Because we don't explicitly specify a column name, Doctrine assumes the field
-name is also the column name. In the example we configured the property ``id`` to map to the column ``id``
-using the mapping type ``integer``. The field ``text`` is mapped to the column
-``text`` with the default mapping type ``string`` and ``postedAt`` is of the
-datetime type, but mapped to a column called ``posted_at``.
+When we don't explicitly specify a column name via the ``name`` option, Doctrine
+assumes the field name is also the column name. This means that:
+
+* the ``id`` property will map to the column ``id`` using the type ``integer``;
+* the ``text`` property will map to the column ``text`` with the default mapping type ``string``;
+* the ``postedAt`` property will map to the ``posted_at`` column with the ``datetime`` type.
 
 The Column annotation has some more attributes. Here is a complete
 list:
@@ -208,16 +208,18 @@ list:
 - ``options``: (optional) Key-value pairs of options that get passed
   to the underlying database platform when generating DDL statements.
 
+.. _reference-mapping-types:
+
 Doctrine Mapping Types
 ----------------------
 
 The ``type`` option used in the ``@Column`` accepts any of the existing
 Doctrine types or even your own custom types. A Doctrine type defines
-the conversion between PHP and SQL types, indepedant from the database vendor
+the conversion between PHP and SQL types, independent from the database vendor
 you are using. All Mapping Types that ship with Doctrine are fully portable
 between the supported database systems.
 
-As an example the Doctrine Mapping Type ``string`` defines the
+As an example, the Doctrine Mapping Type ``string`` defines the
 mapping from a PHP string to a SQL VARCHAR (or VARCHAR2 etc.
 depending on the RDBMS brand). Here is a quick overview of the
 built-in mapping types:
@@ -278,7 +280,7 @@ A cookbook article shows how to define :doc:`your own custom mapping types
 Identifiers / Primary Keys
 --------------------------
 
-Every entity class requires an identifier/primary key. You can select
+Every entity class must have an identifier/primary key. You can select
 the field that serves as the identifier with the ``@Id``
 annotation.
 
@@ -331,7 +333,7 @@ Identifier Generation Strategies
 The previous example showed how to use the default identifier
 generation strategy without knowing the underlying database with
 the AUTO-detection strategy. It is also possible to specify the
-identifier generation strategy more explicitly, which allows to
+identifier generation strategy more explicitly, which allows you to
 make use of some additional features.
 
 Here is the list of possible generation strategies: