rdbms: document Database::doQuery() return value

Removed random @throws tag from a subclass while at it

Change-Id: I1cad1f66b62bb4a306feb5c773ed5556891f82a7

diff --git a/includes/db/DatabaseOracle.php b/includes/db/DatabaseOracle.php
index 6af6de5..aae4492 100644 (file)
--- a/includes/db/DatabaseOracle.php
+++ b/includes/db/DatabaseOracle.php
@@ -184,6 +184,10 @@ class DatabaseOracle extends Database {
                return $this->trxLevel ? OCI_NO_AUTO_COMMIT : OCI_COMMIT_ON_SUCCESS;
        }
 
+       /**
+        * @param string $sql
+        * @return bool|mixed|ORAResult
+        */
        protected function doQuery( $sql ) {
                wfDebug( "SQL: [$sql]\n" );
                if ( !StringUtils::isUtf8( $sql ) ) {

diff --git a/includes/libs/rdbms/database/Database.php b/includes/libs/rdbms/database/Database.php
index b3597df..bafdb44 100644 (file)
--- a/includes/libs/rdbms/database/Database.php
+++ b/includes/libs/rdbms/database/Database.php
@@ -1019,13 +1019,22 @@ abstract class Database implements IDatabase, IMaintainableDatabase, LoggerAware
        }
 
        /**
-        * Run a query and return a DBMS-dependent wrapper (that has all IResultWrapper methods)
+        * Run a query and return a DBMS-dependent wrapper or boolean
         *
-        * This might return things, such as mysqli_result, that do not formally implement
-        * IResultWrapper, but nonetheless implement all of its methods correctly
+        * For SELECT queries, this returns either:
+        *   - a) A driver-specific value/resource, only on success. This can be iterated
+        *        over by calling fetchObject()/fetchRow() until there are no more rows.
+        *        Alternatively, the result can be passed to resultObject() to obtain a
+        *        ResultWrapper instance which can then be iterated over via "foreach".
+        *   - b) False, on any query failure
         *
-        * @param string $sql SQL query.
-        * @return IResultWrapper|bool Iterator to feed to fetchObject/fetchRow; false on failure
+        * For non-SELECT queries, this returns either:
+        *   - a) A driver-specific value/resource, only on success
+        *   - b) True, only on success (e.g. no meaningful result other than "OK")
+        *   - c) False, on any query failure
+        *
+        * @param string $sql SQL query
+        * @return mixed|bool An object, resource, or true on success; false on failure
         */
        abstract protected function doQuery( $sql );
 

diff --git a/includes/libs/rdbms/database/DatabaseMssql.php b/includes/libs/rdbms/database/DatabaseMssql.php
index a6027e6..6e50f5f 100644 (file)
--- a/includes/libs/rdbms/database/DatabaseMssql.php
+++ b/includes/libs/rdbms/database/DatabaseMssql.php
@@ -157,7 +157,6 @@ class DatabaseMssql extends Database {
        /**
         * @param string $sql
         * @return bool|MssqlResultWrapper|resource
-        * @throws DBUnexpectedError
         */
        protected function doQuery( $sql ) {
                // several extensions seem to think that all databases support limits

diff --git a/includes/libs/rdbms/database/DatabaseMysqli.php b/includes/libs/rdbms/database/DatabaseMysqli.php
index ad9b0a4..a3907ca 100644 (file)
--- a/includes/libs/rdbms/database/DatabaseMysqli.php
+++ b/includes/libs/rdbms/database/DatabaseMysqli.php
@@ -37,7 +37,7 @@ use stdClass;
 class DatabaseMysqli extends DatabaseMysqlBase {
        /**
         * @param string $sql
-        * @return mysqli_result
+        * @return mysqli_result|bool
         */
        protected function doQuery( $sql ) {
                $conn = $this->getBindingHandle();

diff --git a/includes/libs/rdbms/database/DatabasePostgres.php b/includes/libs/rdbms/database/DatabasePostgres.php
index 381b1fd..8aec1ac 100644 (file)
--- a/includes/libs/rdbms/database/DatabasePostgres.php
+++ b/includes/libs/rdbms/database/DatabasePostgres.php
@@ -216,6 +216,10 @@ class DatabasePostgres extends Database {
                        !preg_match( '/^SELECT\s+pg_(try_|)advisory_\w+\(/', $sql );
        }
 
+       /**
+        * @param string $sql
+        * @return bool|mixed|resource
+        */
        public function doQuery( $sql ) {
                $conn = $this->getBindingHandle();