From: Aaron Schulz <aschulz@wikimedia.org>
Date: Fri, 1 Mar 2019 02:21:49 +0000 (-0800)
Subject: rdbms: document Database::doQuery() return value
X-Git-Tag: 1.34.0-rc.0~2692^2
X-Git-Url: http://git.cyclocoop.org/%7B%24www_url%7Dadmin/membres/fiche.php?a=commitdiff_plain;h=6ab386219e3d01d8dbe606d9bbfcc45f27125a8c;p=lhc%2Fweb%2Fwiklou.git

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 6af6de52fe..aae44927e6 100644
--- 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 b3597df019..bafdb44b1d 100644
--- 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 a6027e6bea..6e50f5f103 100644
--- 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 ad9b0a4906..a3907caa06 100644
--- 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 381b1fd9c6..8aec1acaea 100644
--- 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();