Fix and improve docs

docs/en/reference/caching.rst

@@ -47,4 +47,4 @@ object is closed:
 
 .. warning::
 
-    When using the cache layer not all fetch modes are supported. See the code of the `ResultCacheStatement <https://github.com/doctrine/dbal/blob/master/lib/Doctrine/DBAL/Cache/ResultCacheStatement.php>`_ for details.
+    When using the cache layer not all fetch modes are supported. See the code of the ``Doctrine\DBAL\Cache\ResultCacheStatement`` for details.

docs/en/reference/platforms.rst

@@ -17,8 +17,8 @@ instance by calling the ``getDatabasePlatform()`` method.
     $platform = $conn->getDatabasePlatform();
 
 Each database driver has a platform associated with it by default.
-Several drivers also share the same platform, for example PDO\_OCI
-and OCI8 share the ``OraclePlatform``.
+Several drivers also share the same platform, for example ``PDO_OCI``
+and ``OCI8`` share the ``OraclePlatform``.
 
 Doctrine provides abstraction for different versions of platforms
 if necessary to represent their specific features and dialects.

docs/en/reference/schema-manager.rst

@@ -22,7 +22,7 @@ available methods to learn about your database schema:
     methods are *NOT* quoted automatically! Identifier quoting is
     really difficult to do manually in a consistent way across
     different databases. You have to manually quote the identifiers
-    when you accept data from user- or other sources not under your
+    when you accept data from user or other sources not under your
     control.
 
 listDatabases()

docs/en/reference/schema-representation.rst

@@ -126,7 +126,7 @@ Vendor specific options
 
 The following options are completely vendor specific and absolutely not portable:
 
--  **columnDefinition**: The custom column declaration SQL snippet to use instead
+-  **columnDefinition** (string): The custom column declaration SQL snippet to use instead
    of the generated SQL by Doctrine. Defaults to ``null``. This can useful to add
    vendor specific declaration information that is not evaluated by Doctrine
    (such as the ``ZEROFILL`` attribute on MySQL).

docs/en/reference/sharding_azure_tutorial.rst

@@ -26,19 +26,21 @@ Install Doctrine
 
 For this tutorial we will install Doctrine and the Sharding Extension through
 `Composer <http://getcomposer.org>`_ which is the easiest way to install
-Doctrine. Composer is a new package manager for PHP. Download the
+Doctrine. Composer is a package manager for PHP. Download the
 ``composer.phar`` from their website and put it into a newly created folder for
 this tutorial. Now create a ``composer.json`` file in this project root with
 the following content:
 
+.. code-block:: json
+
     {
         "require": {
             "doctrine/dbal": "2.2.2",
             "doctrine/shards": "0.2"
         }
     }
 
-Open up the commandline and switch to your tutorial root directory, then call
+Open up the command line and switch to your tutorial root directory, then call
 ``php composer.phar install``. It will grab the code and install it into the
 ``vendor`` subdirectory of your project. It also creates an autoloader, so that
 we don't have to care about this.
@@ -324,10 +326,10 @@ executed this command.
     $shardManager->splitFederation(60);
 
 This little script uses the shard manager with a special method only existing
-on the SQL AZure implementation ``splitFederation``. It accepts a value at
+on the SQL Azure implementation ``splitFederation``. It accepts a value at
 at which the split is executed.
 
-If you reexecute the ``view_federation_members.php`` script you can now see
+If you re-execute the ``view_federation_members.php`` script you can now see
 that there are two federation members instead of just one as before. You can
 see with the ``rangeLow`` and ``rangeHigh`` parameters what customers and
 related entries are now served by which federation.
@@ -403,7 +405,7 @@ Querying data with filtering on
 
 One special feature of SQL Azure is the possibility to database level filtering
 based on the sharding distribution values. This means that SQL Azure will add
-WHERE clauses with distributionkey=current distribution value conditions to
+``WHERE`` clauses with ``distributionkey=current`` distribution value conditions to
 each distribution key.
 
 .. code-block:: php

docs/en/reference/supporting-other-databases.rst

@@ -15,7 +15,7 @@ For an already supported platform but unsupported driver you only
 need to implement the first three interfaces, since the SQL
 Generation and Schema Management is already supported by the
 respective platform and schema instances. You can also make use of
-several Abstract Unittests in the ``\Doctrine\Tests\DBAL`` package
+several Abstract unit tests in the ``\Doctrine\Tests\DBAL`` package
 to check if your platform behaves like all the others which is
 necessary for SchemaTool support, namely:
 
@@ -28,9 +28,9 @@ contributed back to Doctrine to make it an even better product.
 Implementation Steps in Detail
 ------------------------------
 
-1. Add your driver shortcut to class-name `Doctrine\DBAL\DriverManager`.
+1. Add your driver shortcut to the ``Doctrine\DBAL\DriverManager`` class.
 2. Make a copy of tests/dbproperties.xml.dev and adjust the values to your driver shortcut and testdatabase.
 3. Create three new classes implementing ``\Doctrine\DBAL\Driver\Connection``, ``\Doctrine\DBAL\Driver\Statement``
    and ``Doctrine\DBAL\Driver``. You can take a look at the ``Doctrine\DBAL\Driver\OCI8`` driver.
-4. You can run the testsuite of your new database driver by calling "phpunit -c .". You can set your own settings in the phpunit.xml file.
+4. You can run the test suite of your new database driver by calling ``phpunit``. You can set your own settings in the phpunit.xml file.
 5. Start implementing AbstractPlatform and AbstractSchemaManager. Other implementations should serve as good examples.