From 3752149766a732963a0a6e22cb4f7d5ea339c84c Mon Sep 17 00:00:00 2001 From: greeflas Date: Tue, 8 Sep 2020 00:17:10 +0300 Subject: [PATCH] Fix and improve docs --- docs/en/reference/caching.rst | 2 +- docs/en/reference/platforms.rst | 4 ++-- docs/en/reference/schema-manager.rst | 2 +- docs/en/reference/schema-representation.rst | 2 +- docs/en/reference/sharding_azure_tutorial.rst | 12 +++++++----- docs/en/reference/supporting-other-databases.rst | 6 +++--- 6 files changed, 15 insertions(+), 13 deletions(-) diff --git a/docs/en/reference/caching.rst b/docs/en/reference/caching.rst index 5a2daf0b317..d699adaef5a 100644 --- a/docs/en/reference/caching.rst +++ b/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 `_ for details. + When using the cache layer not all fetch modes are supported. See the code of the ``Doctrine\DBAL\Cache\ResultCacheStatement`` for details. diff --git a/docs/en/reference/platforms.rst b/docs/en/reference/platforms.rst index 32ef74304ea..07880c5d677 100644 --- a/docs/en/reference/platforms.rst +++ b/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. diff --git a/docs/en/reference/schema-manager.rst b/docs/en/reference/schema-manager.rst index d14bc930e70..b4637961c9b 100644 --- a/docs/en/reference/schema-manager.rst +++ b/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() diff --git a/docs/en/reference/schema-representation.rst b/docs/en/reference/schema-representation.rst index e1beff8a0df..04294e980dc 100644 --- a/docs/en/reference/schema-representation.rst +++ b/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). diff --git a/docs/en/reference/sharding_azure_tutorial.rst b/docs/en/reference/sharding_azure_tutorial.rst index 71a4fab5594..42fca1e62b5 100644 --- a/docs/en/reference/sharding_azure_tutorial.rst +++ b/docs/en/reference/sharding_azure_tutorial.rst @@ -26,11 +26,13 @@ Install Doctrine For this tutorial we will install Doctrine and the Sharding Extension through `Composer `_ 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", @@ -38,7 +40,7 @@ the following content: } } -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 diff --git a/docs/en/reference/supporting-other-databases.rst b/docs/en/reference/supporting-other-databases.rst index 797fe76401d..f5e2af1037a 100644 --- a/docs/en/reference/supporting-other-databases.rst +++ b/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.