Merge "JSON formatversion=2 is no longer experimental"

[lhc/web/wiklou.git] / includes / libs / rdbms / database / IDatabase.php

diff --git a/includes/libs/rdbms/database/IDatabase.php b/includes/libs/rdbms/database/IDatabase.php
index 1973322..532d818 100644 (file)
--- a/includes/libs/rdbms/database/IDatabase.php
+++ b/includes/libs/rdbms/database/IDatabase.php
@@ -595,15 +595,7 @@ interface IDatabase {
         * Execute a SELECT query constructed using the various parameters provided.
         * See below for full details of the parameters.
         *
-        * @param string|array $table Table name
-        * @param string|array $vars Field names
-        * @param string|array $conds Conditions
-        * @param string $fname Caller function name
-        * @param array $options Query options
-        * @param array $join_conds Join conditions
-        *
-        *
-        * @param string|array $table
+        * @param string|array $table Table name(s)
         *
         * May be either an array of table names, or a single string holding a table
         * name. If an array is given, table aliases can be specified, for example:
@@ -638,7 +630,7 @@ interface IDatabase {
         * Do not use untrusted user input as a table name. Alias names should
         * not have characters outside of the Basic multilingual plane.
         *
-        * @param string|array $vars
+        * @param string|array $vars Field name(s)
         *
         * May be either a field name or an array of field names. The field names
         * can be complete fragments of SQL, for direct inclusion into the SELECT
@@ -685,7 +677,9 @@ interface IDatabase {
         *
         * Use an empty array, string, or '*' to update all rows.
         *
-        * @param string|array $options
+        * @param string $fname Caller function name
+        *
+        * @param string|array $options Query options
         *
         * Optional: Array of query options. Boolean options are specified by
         * including them in the array as a string value with a numeric key, for
@@ -741,7 +735,7 @@ interface IDatabase {
         *    - SQL_NO_CACHE
         *
         *
-        * @param string|array $join_conds
+        * @param string|array $join_conds Join conditions
         *
         * Optional associative array of table-specific join conditions. In the
         * most common case, this is unnecessary, since the join condition can be
@@ -930,8 +924,7 @@ interface IDatabase {
         * @param array $a Array of rows to insert
         * @param string $fname Calling function name (use __METHOD__) for logs/profiling
         * @param array $options Array of options
-        *
-        * @return bool
+        * @return bool Return true if no exception was thrown (deprecated since 1.33)
         * @throws DBError
         */
        public function insert( $table, $a, $fname = __METHOD__, $options = [] );
@@ -954,7 +947,7 @@ interface IDatabase {
         * @param array $options An array of UPDATE options, can be:
         *   - IGNORE: Ignore unique key conflicts
         *   - LOW_PRIORITY: MySQL-specific, see MySQL manual.
-        * @return bool
+        * @return bool Return true if no exception was thrown (deprecated since 1.33)
         * @throws DBError
         */
        public function update( $table, $values, $conds, $fname = __METHOD__, $options = [] );
@@ -1268,7 +1261,7 @@ interface IDatabase {
         *   things like "field = field + 1" or similar computed values.
         * @param string $fname Calling function name (use __METHOD__) for logs/profiling
         * @throws DBError
-        * @return bool
+        * @return bool Return true if no exception was thrown (deprecated since 1.33)
         */
        public function upsert(
                $table, array $rows, array $uniqueIndexes, array $set, $fname = __METHOD__
@@ -1306,7 +1299,7 @@ interface IDatabase {
         *   for the format. Use $conds == "*" to delete all rows
         * @param string $fname Name of the calling function
         * @throws DBUnexpectedError
-        * @return bool|IResultWrapper
+        * @return bool Return true if no exception was thrown (deprecated since 1.33)
         * @throws DBError
         */
        public function delete( $table, $conds, $fname = __METHOD__ );
@@ -1344,7 +1337,7 @@ interface IDatabase {
         * @param array $selectJoinConds Join conditions for the SELECT part of the query, see
         *    IDatabase::select() for details.
         *
-        * @return bool
+        * @return bool Return true if no exception was thrown (deprecated since 1.33)
         * @throws DBError
         */
        public function insertSelect( $destTable, $srcTable, $varMap, $conds,
@@ -1478,6 +1471,10 @@ interface IDatabase {
        /**
         * Wait for the replica DB to catch up to a given master position
         *
+        * Note that this does not start any new transactions. If any existing transaction
+        * is flushed, and this is called, then queries will reflect the point the DB was synced
+        * up to (on success) without interference from REPEATABLE-READ snapshots.
+        *
         * @param DBMasterPos $pos
         * @param int $timeout The maximum number of seconds to wait for synchronisation
         * @return int|null Zero if the replica DB was past that position already,