Did some more work on DBAL ReST documentation.

reference/en/index.rst → en/index.rst

@@ -9,25 +9,24 @@ Welcome to Doctrine DBAL's documentation!
 Contents:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
+   :numbered:
 
-   introduction
-   architecture
-   configuration
-   data-retrieval-and-manipulation
-   transactions
-   platforms
-   types
-   schema-manager
-   schema-representation
-   events
-   supporting-other-databases
-   known-vendor-issues
+   reference/introduction
+   reference/architecture
+   reference/configuration
+   reference/data-retrieval-and-manipulation
+   reference/transactions
+   reference/platforms
+   reference/types
+   reference/schema-manager
+   reference/schema-representation
+   reference/events
+   reference/supporting-other-databases
+   reference/known-vendor-issues
 
 Indices and tables
 ==================
 
-* :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`
 

reference/en/configuration.rst → en/reference/configuration.rst

@@ -7,7 +7,7 @@ Getting a Connection
 You can get a DBAL Connection through the
 ``Doctrine\DBAL\DriverManager`` class.
 
-::
+.. code-block:: php
 
     <?php
     $config = new \Doctrine\DBAL\Configuration();
@@ -143,7 +143,6 @@ Custom Driver Options
 
 The ``driverOptions`` option allows to pass arbitrary options
 through to the driver. This is equivalent to the 4th argument of
-the
-`PDO constructor <http://php.net/manual/en/pdo.construct.php>`_.
+the `PDO constructor <http://php.net/manual/en/pdo.construct.php>`_.
 
 

reference/en/data-retrieval-and-manipulation.rst → en/reference/data-retrieval-and-manipulation.rst

@@ -12,7 +12,7 @@ prepare()
 Prepare a given sql statement and return the
 ``\Doctrine\DBAL\Driver\Statement`` instance:
 
-::
+.. code-block:: php
 
     <?php
     $statement = $conn->prepare('SELECT * FROM user');
@@ -34,7 +34,7 @@ executeUpdate()
 Executes a prepared statement with the given sql and parameters and
 returns the affected rows count:
 
-::
+.. code-block:: php
 
     <?php
     $count = $conn->executeUpdate('UPDATE user SET username = ? WHERE id = ?', array('jwage', 1));
@@ -51,7 +51,7 @@ executeQuery()
 Creates a prepared statement for the given sql and passes the
 parameters to the execute method, then returning the statement:
 
-::
+.. code-block:: php
 
     <?php
     $statement = $conn->execute('SELECT * FROM user WHERE username = ?', array('jwage'));
@@ -74,7 +74,7 @@ fetchAll()
 
 Execute the query and fetch all results into an array:
 
-::
+.. code-block:: php
 
     <?php
     $users = $conn->fetchAll('SELECT * FROM user');
@@ -93,7 +93,7 @@ fetchArray()
 
 Numeric index retrieval of first result row of the given query:
 
-::
+.. code-block:: php
 
     <?php
     $user = $conn->fetchArray('SELECT * FROM user WHERE username = ?', array('jwage'));
@@ -110,7 +110,7 @@ fetchColumn()
 
 Retrieve only the given column of the first result row.
 
-::
+.. code-block:: php
 
     <?php
     $username = $conn->fetchColumn('SELECT username FROM user WHERE id = ?', array(1), 0);
@@ -121,7 +121,7 @@ fetchAssoc()
 
 Retrieve assoc row of the first result row.
 
-::
+.. code-block:: php
 
     <?php
     $user = $conn->fetchAssoc('SELECT * FROM user WHERE username = ?', array('jwage'));
@@ -140,7 +140,7 @@ delete()
 Delete all rows of a table matching the given identifier, where
 keys are column names.
 
-::
+.. code-block:: php
 
     <?php
     $conn->delete('user', array('id' => 1));
@@ -152,7 +152,7 @@ insert()
 Insert a row into the given table name using the key value pairs of
 data.
 
-::
+.. code-block:: php
 
     <?php
     $conn->insert('user', array('username' => 'jwage'));
@@ -164,7 +164,7 @@ update()
 Update all rows for the matching key value identifiers with the
 given data.
 
-::
+.. code-block:: php
 
     <?php
     $conn->update('user', array('username' => 'jwage'), array('id' => 1));
@@ -182,7 +182,7 @@ quote()
 
 Quote a value:
 
-::
+.. code-block:: php
 
     <?php
     $quoted = $conn->quote('value');
@@ -193,7 +193,7 @@ quoteIdentifier()
 
 Quote an identifier according to the platform details.
 
-::
+.. code-block:: php
 
     <?php
     $quoted = $conn->quoteIdentifier('id');

reference/en/events.rst → en/reference/events.rst

@@ -32,7 +32,7 @@ Doctrine is already shipped with two implementations for the
 You can register events by subscribing them to the ``EventManager``
 instance passed to the Connection factory:
 
-::
+.. code-block:: php
 
     <?php
     $evm = new EventManager();

reference/en/introduction.rst → en/reference/introduction.rst

@@ -19,7 +19,7 @@ the ``Doctrine\Common`` and ``Doctrine\DBAL`` namespaces. Once you
 have the Common and DBAL namespaces you must setup a class loader
 to be able to autoload the classes:
 
-::
+.. code-block:: php
 
     <?php
     use Doctrine\Common\ClassLoader;

reference/en/known-vendor-issues.rst → en/reference/known-vendor-issues.rst

@@ -105,15 +105,15 @@ OCI8: SQL Queries with Question Marks
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 We had to implement a question mark to named parameter translation
-inside the OCI8 DBAL Driver. This means that you cannot execute
-queries that contain question marks in the SQL string. For
-example:
+inside the OCI8 DBAL Driver. It works as a very simple parser with two states: Inside Literal, Outside Literal.
+From our perspective it should be working in all cases, but you have to be careful with certain
+queries:
 
 .. code-block:: sql
 
     SELECT * FROM users WHERE name = 'bar?'
 
-Will be rewritten into:
+Could in case of a bug with the parser be rewritten into:
 
 .. code-block:: sql
 
@@ -123,17 +123,13 @@ For this reason you should always use prepared statements with
 Oracle OCI8, never use string literals inside the queries. A query
 for the user 'bar?' should look like:
 
-::
+.. code-block:: php
 
     $sql = 'SELECT * FROM users WHERE name = ?'
     $stmt = $conn->prepare($sql);
     $stmt->bindValue(1, 'bar?');
     $stmt->execute();
 
-We will probably fix this issue in the future by implementing a
-little parser inside the OCI8 Driver that can detect the difference
-between question mark needles and literal questions marks.
-
 OCI-LOB instances
 ~~~~~~~~~~~~~~~~~