Merge pull request #1096 from simonharris/master

Changes for grammar and clarity

docs/en/reference/caching.rst

@@ -4,9 +4,9 @@ Caching
 Doctrine provides cache drivers in the ``Common`` package for some
 of the most popular caching implementations such as APC, Memcache
 and Xcache. We also provide an ``ArrayCache`` driver which stores
-the data in a PHP array. Obviously, the cache does not live between
-requests but this is useful for testing in a development
-environment.
+the data in a PHP array. Obviously, when using ``ArrayCache``, the 
+cache does not persist between requests, but this is useful for 
+testing in a development environment.
 
 Cache Drivers
 -------------
@@ -14,20 +14,19 @@ Cache Drivers
 The cache drivers follow a simple interface that is defined in
 ``Doctrine\Common\Cache\Cache``. All the cache drivers extend a
 base class ``Doctrine\Common\Cache\AbstractCache`` which implements
-the before mentioned interface.
+this interface.
 
-The interface defines the following methods for you to publicly
-use.
+The interface defines the following public methods for you to implement:
 
 
--  fetch($id) - Fetches an entry from the cache.
--  contains($id) - Test if an entry exists in the cache.
--  save($id, $data, $lifeTime = false) - Puts data into the cache.
--  delete($id) - Deletes a cache entry.
+-  fetch($id) - Fetches an entry from the cache
+-  contains($id) - Test if an entry exists in the cache
+-  save($id, $data, $lifeTime = false) - Puts data into the cache
+-  delete($id) - Deletes a cache entry
 
 Each driver extends the ``AbstractCache`` class which defines a few
 abstract protected methods that each of the drivers must
-implement.
+implement:
 
 
 -  \_doFetch($id)
@@ -35,8 +34,8 @@ implement.
 -  \_doSave($id, $data, $lifeTime = false)
 -  \_doDelete($id)
 
-The public methods ``fetch()``, ``contains()``, etc. utilize the
-above protected methods that are implemented by the drivers. The
+The public methods ``fetch()``, ``contains()`` etc. use the
+above protected methods which are implemented by the drivers. The
 code is organized this way so that the protected methods in the
 drivers do the raw interaction with the cache implementation and
 the ``AbstractCache`` can build custom functionality on top of
@@ -65,7 +64,7 @@ Memcache
 
 In order to use the Memcache cache driver you must have it compiled
 and enabled in your php.ini. You can read about Memcache
-` on the PHP website <http://php.net/memcache>`_. It will
+`on the PHP website <http://php.net/memcache>`_. It will
 give you a little background information about what it is and how
 you can use it as well as how to install it.
 
@@ -90,7 +89,7 @@ Memcache.
 
 In order to use the Memcached cache driver you must have it compiled
 and enabled in your php.ini. You can read about Memcached
-` on the PHP website <http://php.net/memcached>`_. It will
+`on the PHP website <http://php.net/memcached>`_. It will
 give you a little background information about what it is and how
 you can use it as well as how to install it.
 
@@ -129,10 +128,10 @@ Redis
 ~~~~~
 
 In order to use the Redis cache driver you must have it compiled
-and enabled in your php.ini. You can read about what is Redis
+and enabled in your php.ini. You can read about what Redis is
 `from here <http://redis.io/>`_. Also check
 `A PHP extension for Redis <https://github.com/nicolasff/phpredis/>`_ for how you can use
-and install Redis PHP extension.
+and install the Redis PHP extension.
 
 Below is a simple example of how you could use the Redis cache
 driver by itself.
@@ -151,8 +150,8 @@ Using Cache Drivers
 -------------------
 
 In this section we'll describe how you can fully utilize the API of
-the cache drivers to save cache, check if some cache exists, fetch
-the cached data and delete the cached data. We'll use the
+the cache drivers to save data to a cache, check if some cached data 
+exists, fetch the cached data and delete the cached data. We'll use the
 ``ArrayCache`` implementation as our example here.
 
 .. code-block:: php
@@ -163,7 +162,7 @@ the cached data and delete the cached data. We'll use the
 Saving
 ~~~~~~
 
-To save some data to the cache driver it is as simple as using the
+Saving some data to the cache driver is as simple as using the
 ``save()`` method.
 
 .. code-block:: php
@@ -172,7 +171,7 @@ To save some data to the cache driver it is as simple as using the
     $cacheDriver->save('cache_id', 'my_data');
 
 The ``save()`` method accepts three arguments which are described
-below.
+below:
 
 
 -  ``$id`` - The cache id
@@ -195,7 +194,7 @@ object, etc.
 Checking
 ~~~~~~~~
 
-Checking whether some cache exists is very simple, just use the
+Checking whether cached data exists is very simple: just use the
 ``contains()`` method. It accepts a single argument which is the ID
 of the cache entry.
 
@@ -213,7 +212,7 @@ Fetching
 
 Now if you want to retrieve some cache entry you can use the
 ``fetch()`` method. It also accepts a single argument just like
-``contains()`` which is the ID of the cache entry.
+``contains()`` which is again the ID of the cache entry.
 
 .. code-block:: php
 
@@ -249,7 +248,7 @@ the ``deleteAll()`` method.
 Namespaces
 ~~~~~~~~~~
 
-If you heavily use caching in your application and utilize it in
+If you heavily use caching in your application and use it in
 multiple parts of your application, or use it in different
 applications on the same server you may have issues with cache
 naming collisions. This can be worked around by using namespaces.
@@ -265,8 +264,8 @@ Integrating with the ORM
 ------------------------
 
 The Doctrine ORM package is tightly integrated with the cache
-drivers to allow you to improve performance of various aspects of
-Doctrine by just simply making some additional configurations and
+drivers to allow you to improve the performance of various aspects of
+Doctrine by simply making some additional configurations and
 method calls.
 
 Query Cache
@@ -374,9 +373,9 @@ the cache driver.
 Clearing the Cache
 ------------------
 
-We've already shown you previously how you can use the API of the
+We've already shown you how you can use the API of the
 cache drivers to manually delete cache entries. For your
-convenience we offer a command line task for you to help you with
+convenience we offer a command line task to help you with
 clearing the query, result and metadata cache.
 
 From the Doctrine command line you can run the following command.
@@ -408,7 +407,7 @@ To clear the result cache use the ``--result`` option.
     $ ./doctrine clear-cache --result
 
 When you use the ``--result`` option you can use some other options
-to be more specific about what queries result sets you want to
+to be more specific about which queries' result sets you want to
 clear.
 
 Just like the API of the cache drivers you can clear based on an
@@ -418,19 +417,19 @@ ID, regular expression, prefix or suffix.
 
     $ ./doctrine clear-cache --result --id=cache_id
 
-Or if you want to clear based on a regular expressions.
+Or if you want to clear based on a regular expressions:
 
 .. code-block:: php
 
     $ ./doctrine clear-cache --result --regex=users_.*
 
-Or with a prefix.
+Or with a prefix:
 
 .. code-block:: php
 
     $ ./doctrine clear-cache --result --prefix=users_
 
-And finally with a suffix.
+And finally with a suffix:
 
 .. code-block:: php
 
@@ -447,15 +446,15 @@ And finally with a suffix.
 Cache Slams
 -----------
 
-Something to be careful of when utilizing the cache drivers is
-cache slams. If you have a heavily trafficked website with some
+Something to be careful of when using the cache drivers is
+"cache slams". Imagine you have a heavily trafficked website with some
 code that checks for the existence of a cache record and if it does
 not exist it generates the information and saves it to the cache.
-Now if 100 requests were issued all at the same time and each one
-sees the cache does not exist and they all try and insert the same
+Now, if 100 requests were issued all at the same time and each one
+sees the cache does not exist and they all try to insert the same
 cache entry it could lock up APC, Xcache, etc. and cause problems.
 Ways exist to work around this, like pre-populating your cache and
-not letting your users requests populate the cache.
+not letting your users' requests populate the cache.
 
 You can read more about cache slams
 `in this blog post <http://notmysock.org/blog/php/user-cache-timebomb.html>`_.