From: Sam Reed <reedy@users.mediawiki.org>
Date: Fri, 16 Sep 2011 17:58:50 +0000 (+0000)
Subject: Moar documentations
X-Git-Tag: 1.31.0-rc.0~27611
X-Git-Url: https://git.cyclocoop.org/%28%28?a=commitdiff_plain;h=4d8c6dee24e10bb8f0db1e0f2407d8d475c2fb22;p=lhc%2Fweb%2Fwiklou.git

Moar documentations
---

diff --git a/includes/GlobalFunctions.php b/includes/GlobalFunctions.php
index d7a55c9384..33cff2c59e 100644
--- a/includes/GlobalFunctions.php
+++ b/includes/GlobalFunctions.php
@@ -3153,6 +3153,8 @@ function wfWikiID() {
  *
  * @param $wiki String
  * @param $bits String
+ *
+ * @return array
  */
 function wfSplitWikiID( $wiki ) {
 	$bits = explode( '-', $wiki, 2 );
diff --git a/includes/db/Database.php b/includes/db/Database.php
index 086faaaa62..153443fcda 100644
--- a/includes/db/Database.php
+++ b/includes/db/Database.php
@@ -224,6 +224,8 @@ abstract class DatabaseBase implements DatabaseType {
 	protected $mDefaultBigSelects = null;
 	protected $mSchemaVars = false;
 
+	protected $preparedArgs;
+
 # ------------------------------------------------------------------------------
 # Accessors
 # ------------------------------------------------------------------------------
@@ -290,7 +292,7 @@ abstract class DatabaseBase implements DatabaseType {
 	 * code should use lastErrno() and lastError() to handle the
 	 * situation as appropriate.
 	 *
-	 * @param $ignoreErrors
+	 * @param $ignoreErrors bool|null
 	 *
 	 * @return The previous value of the flag.
 	 */
@@ -433,6 +435,8 @@ abstract class DatabaseBase implements DatabaseType {
 	/**
 	 * Returns true if this database does an implicit order by when the column has an index
 	 * For example: SELECT page_title FROM page LIMIT 1
+	 *
+	 * @return bool
 	 */
 	function implicitOrderby() {
 		return true;
@@ -530,6 +534,10 @@ abstract class DatabaseBase implements DatabaseType {
 
 	/**
 	 * General read-only accessor
+	 *
+	 * @param $name string
+	 *
+	 * @return string
 	 */
 	function getProperty( $name ) {
 		return $this->$name;
@@ -707,7 +715,7 @@ abstract class DatabaseBase implements DatabaseType {
 	 * The DBMS-dependent part of query()
 	 *
 	 * @param  $sql String: SQL query.
-	 * @return Result object to feed to fetchObject, fetchRow, ...; or false on failure
+	 * @return ResultWrapper Result object to feed to fetchObject, fetchRow, ...; or false on failure
 	 */
 	protected abstract function doQuery( $sql );
 
@@ -1182,7 +1190,6 @@ abstract class DatabaseBase implements DatabaseType {
 	 * @param $options Array Query options
 	 * @param $join_conds Array Join conditions
 	 *
-	 *
 	 * @param $table string|array
 	 *
 	 * May be either an array of table names, or a single string holding a table
@@ -1429,8 +1436,8 @@ abstract class DatabaseBase implements DatabaseType {
 	 * Takes the same arguments as DatabaseBase::select().
 	 *
 	 * @param $table String: table name
-	 * @param $vars Array: unused
-	 * @param $conds Array: filters on the table
+	 * @param Array|string $vars : unused
+	 * @param Array|string $conds : filters on the table
 	 * @param $fname String: function name for profiling
 	 * @param $options Array: options for select
 	 * @return Integer: row count
diff --git a/includes/db/DatabaseError.php b/includes/db/DatabaseError.php
index b7fb1b2273..2fe409b8f2 100644
--- a/includes/db/DatabaseError.php
+++ b/includes/db/DatabaseError.php
@@ -87,6 +87,11 @@ class DBConnectionError extends DBError {
 		return false;
 	}
 
+	/**
+	 * @param $key
+	 * @param $fallback
+	 * @return string
+	 */
 	function msg( $key, $fallback /*[, params...] */ ) {
 		global $wgLang;
 
diff --git a/includes/db/DatabaseMysql.php b/includes/db/DatabaseMysql.php
index ccc8df322e..c5730772c7 100644
--- a/includes/db/DatabaseMysql.php
+++ b/includes/db/DatabaseMysql.php
@@ -14,6 +14,10 @@
  * @see Database
  */
 class DatabaseMysql extends DatabaseBase {
+
+	/**
+	 * @return string
+	 */
 	function getType() {
 		return 'mysql';
 	}
@@ -138,6 +142,9 @@ class DatabaseMysql extends DatabaseBase {
 		return $success;
 	}
 
+	/**
+	 * @return bool
+	 */
 	function close() {
 		$this->mOpened = false;
 		if ( $this->mConn ) {
@@ -188,6 +195,11 @@ class DatabaseMysql extends DatabaseBase {
 		return $row;
 	}
 
+	/**
+	 * @throws DBUnexpectedError
+	 * @param $res
+	 * @return int
+	 */
 	function numRows( $res ) {
 		if ( $res instanceof ResultWrapper ) {
 			$res = $res->result;
@@ -201,6 +213,10 @@ class DatabaseMysql extends DatabaseBase {
 		return $n;
 	}
 
+	/**
+	 * @param $res
+	 * @return int
+	 */
 	function numFields( $res ) {
 		if ( $res instanceof ResultWrapper ) {
 			$res = $res->result;
@@ -208,6 +224,11 @@ class DatabaseMysql extends DatabaseBase {
 		return mysql_num_fields( $res );
 	}
 
+	/**
+	 * @param $res
+	 * @param $n
+	 * @return string
+	 */
 	function fieldName( $res, $n ) {
 		if ( $res instanceof ResultWrapper ) {
 			$res = $res->result;
@@ -215,7 +236,12 @@ class DatabaseMysql extends DatabaseBase {
 		return mysql_field_name( $res, $n );
 	}
 
-	function insertId() { return mysql_insert_id( $this->mConn ); }
+	/**
+	 * @return int
+	 */
+	function insertId() {
+		return mysql_insert_id( $this->mConn );
+	}
 
 	function dataSeek( $res, $row ) {
 		if ( $res instanceof ResultWrapper ) {
@@ -250,7 +276,12 @@ class DatabaseMysql extends DatabaseBase {
 		return $error;
 	}
 
-	function affectedRows() { return mysql_affected_rows( $this->mConn ); }
+	/**
+	 * @return int
+	 */
+	function affectedRows() {
+		return mysql_affected_rows( $this->mConn );
+	}
 
 	function replace( $table, $uniqueIndexes, $rows, $fname = 'DatabaseMysql::replace' ) {
 		return $this->nativeReplace( $table, $rows, $fname );
@@ -260,6 +291,8 @@ class DatabaseMysql extends DatabaseBase {
 	 * Estimate rows in dataset
 	 * Returns estimated count, based on EXPLAIN output
 	 * Takes same arguments as Database::select()
+	 *
+	 * @return int
 	 */
 	public function estimateRowCount( $table, $vars='*', $conds='', $fname = 'DatabaseMysql::estimateRowCount', $options = array() ) {
 		$options['EXPLAIN'] = true;
@@ -278,6 +311,11 @@ class DatabaseMysql extends DatabaseBase {
 		return $rows;
 	}
 
+	/**
+	 * @param $table string
+	 * @param $field string
+	 * @return bool|MySQLField
+	 */
 	function fieldInfo( $table, $field ) {
 		$table = $this->tableName( $table );
 		$res = $this->query( "SELECT * FROM $table LIMIT 1", __METHOD__, true );
@@ -297,6 +335,8 @@ class DatabaseMysql extends DatabaseBase {
 	/**
 	 * Get information about an index into an object
 	 * Returns false if the index does not exist
+	 *
+	 * @return false|array
 	 */
 	function indexInfo( $table, $index, $fname = 'DatabaseMysql::indexInfo' ) {
 		# SHOW INDEX works in MySQL 3.23.58, but SHOW INDEXES does not.
@@ -322,11 +362,20 @@ class DatabaseMysql extends DatabaseBase {
 		return empty( $result ) ? false : $result;
 	}
 
+	/**
+	 * @param $db
+	 * @return bool
+	 */
 	function selectDB( $db ) {
 		$this->mDBname = $db;
 		return mysql_select_db( $db, $this->mConn );
 	}
 
+	/**
+	 * @param $s string
+	 *
+	 * @return string
+	 */
 	function strencode( $s ) {
 		$sQuoted = mysql_real_escape_string( $s, $this->mConn );
 
@@ -339,15 +388,26 @@ class DatabaseMysql extends DatabaseBase {
 
 	/**
 	 * MySQL uses `backticks` for identifier quoting instead of the sql standard "double quotes".
+	 *
+	 * @param $s string
+	 *
+	 * @return string
 	 */
 	public function addIdentifierQuotes( $s ) {
 		return "`" . $this->strencode( $s ) . "`";
 	}
 
+	/**
+	 * @param $name string
+	 * @return bool
+	 */
 	public function isQuotedIdentifier( $name ) {
-		return strlen($name) && $name[0] == '`' && substr( $name, -1, 1 ) == '`';
+		return strlen( $name ) && $name[0] == '`' && substr( $name, -1, 1 ) == '`';
 	}
 
+	/**
+	 * @return bool
+	 */
 	function ping() {
 		$ping = mysql_ping( $this->mConn );
 		if ( $ping ) {
@@ -516,18 +576,31 @@ class DatabaseMysql extends DatabaseBase {
 		}
 	}
 
+	/**
+	 * @return string
+	 */
 	function getServerVersion() {
 		return mysql_get_server_info( $this->mConn );
 	}
 
+	/**
+	 * @param $index
+	 * @return string
+	 */
 	function useIndexClause( $index ) {
 		return "FORCE INDEX (" . $this->indexName( $index ) . ")";
 	}
 
+	/**
+	 * @return string
+	 */
 	function lowPriorityOption() {
 		return 'LOW_PRIORITY';
 	}
 
+	/**
+	 * @return string
+	 */
 	public static function getSoftwareLink() {
 		return '[http://www.mysql.com/ MySQL]';
 	}
@@ -630,6 +703,8 @@ class DatabaseMysql extends DatabaseBase {
 
 	/**
 	 * Determines if the last failure was due to a deadlock
+	 *
+	 * @return bool
 	 */
 	function wasDeadlock() {
 		return $this->lastErrno() == 1213;
@@ -638,6 +713,8 @@ class DatabaseMysql extends DatabaseBase {
 	/**
 	 * Determines if the last query error was something that should be dealt
 	 * with by pinging the connection and reissuing the query
+	 *
+	 * @return bool
 	 */
 	function wasErrorReissuable() {
 		return $this->lastErrno() == 2013 || $this->lastErrno() == 2006;
@@ -645,6 +722,8 @@ class DatabaseMysql extends DatabaseBase {
 
 	/**
 	 * Determines if the last failure was due to the database being read-only.
+	 *
+	 * @return bool
 	 */
 	function wasReadOnlyError() {
 		return $this->lastErrno() == 1223 ||
@@ -702,6 +781,11 @@ class DatabaseMysql extends DatabaseBase {
 		return $endArray;
 	}
 
+	/**
+	 * @param $tableName
+	 * @param $fName string
+	 * @return bool|ResultWrapper
+	 */
 	public function dropTable( $tableName, $fName = 'DatabaseMysql::dropTable' ) {
 		if( !$this->tableExists( $tableName ) ) {
 			return false;
@@ -735,6 +819,8 @@ class DatabaseMysql extends DatabaseBase {
 
 /**
  * Legacy support: Database == DatabaseMysql
+ *
+ * @deprecated in 1.16
  */
 class Database extends DatabaseMysql {}
 
@@ -759,10 +845,16 @@ class MySQLField implements Field {
 		$this->type = $info->type;
 	}
 
+	/**
+	 * @return string
+	 */
 	function name() {
 		return $this->name;
 	}
 
+	/**
+	 * @return string
+	 */
 	function tableName() {
 		return $this->tableName;
 	}
@@ -771,6 +863,9 @@ class MySQLField implements Field {
 		return $this->type;
 	}
 
+	/**
+	 * @return bool
+	 */
 	function isNullable() {
 		return $this->nullable;
 	}
@@ -779,14 +874,23 @@ class MySQLField implements Field {
 		return $this->default;
 	}
 
+	/**
+	 * @return bool
+	 */
 	function isKey() {
 		return $this->is_key;
 	}
 
+	/**
+	 * @return bool
+	 */
 	function isMultipleKey() {
 		return $this->is_multiple;
 	}
 
+	/**
+	 * @return int
+	 */
 	function maxLength() {
 		return $this->max_length;
 	}
diff --git a/includes/db/DatabaseUtility.php b/includes/db/DatabaseUtility.php
index d1bced6ba1..15ec920fa7 100644
--- a/includes/db/DatabaseUtility.php
+++ b/includes/db/DatabaseUtility.php
@@ -155,6 +155,9 @@ class ResultWrapper implements Iterator {
 		$this->currentRow = null;
 	}
 
+	/**
+	 * @return int
+	 */
 	function current() {
 		if ( is_null( $this->currentRow ) ) {
 			$this->next();
@@ -162,16 +165,25 @@ class ResultWrapper implements Iterator {
 		return $this->currentRow;
 	}
 
+	/**
+	 * @return int
+	 */
 	function key() {
 		return $this->pos;
 	}
 
+	/**
+	 * @return int
+	 */
 	function next() {
 		$this->pos++;
 		$this->currentRow = $this->fetchObject();
 		return $this->currentRow;
 	}
 
+	/**
+	 * @return bool
+	 */
 	function valid() {
 		return $this->current() !== false;
 	}
diff --git a/includes/db/LBFactory_Multi.php b/includes/db/LBFactory_Multi.php
index 61e56e7872..ec2d513da5 100644
--- a/includes/db/LBFactory_Multi.php
+++ b/includes/db/LBFactory_Multi.php
@@ -59,7 +59,7 @@ class LBFactory_Multi extends LBFactory {
 		$required = array( 'sectionsByDB', 'sectionLoads', 'serverTemplate' );
 		$optional = array( 'groupLoadsBySection', 'groupLoadsByDB', 'hostsByName',
 			'externalLoads', 'externalTemplateOverrides', 'templateOverridesByServer',
-			'templateOverridesByCluster', 'masterTemplateOverrides', 
+			'templateOverridesByCluster', 'masterTemplateOverrides',
 			'readOnlyBySection' );
 
 		foreach ( $required as $key ) {
@@ -83,6 +83,10 @@ class LBFactory_Multi extends LBFactory {
 		}
 	}
 
+	/**
+	 * @param $wiki bool|string
+	 * @return string
+	 */
 	function getSectionForWiki( $wiki = false ) {
 		if ( $this->lastWiki === $wiki ) {
 			return $this->lastSection;
@@ -99,7 +103,7 @@ class LBFactory_Multi extends LBFactory {
 	}
 
 	/**
-	 * @param $wiki string
+	 * @param $wiki bool|string
 	 * @return LoadBalancer
 	 */
 	function newMainLB( $wiki = false ) {
@@ -116,7 +120,7 @@ class LBFactory_Multi extends LBFactory {
 	}
 
 	/**
-	 * @param $wiki
+	 * @param $wiki bool|string
 	 * @return LoadBalancer
 	 */
 	function getMainLB( $wiki = false ) {
@@ -172,7 +176,7 @@ class LBFactory_Multi extends LBFactory {
 		$servers = $this->makeServerArray( $template, $loads, $groupLoads );
 		$lb = new LoadBalancer( array(
 			'servers' => $servers,
-			'masterWaitTimeout' => $wgMasterWaitTimeout 
+			'masterWaitTimeout' => $wgMasterWaitTimeout
 		));
 		return $lb;
 	}
@@ -180,6 +184,9 @@ class LBFactory_Multi extends LBFactory {
 	/**
 	 * Make a server array as expected by LoadBalancer::__construct, using a template and load array
 	 *
+	 * @param $template
+	 * @param $loads
+	 * @param $groupLoads
 	 * @return array
 	 */
 	function makeServerArray( $template, $loads, $groupLoads ) {
@@ -220,6 +227,8 @@ class LBFactory_Multi extends LBFactory {
 
 	/**
 	 * Take a group load array indexed by group then server, and reindex it by server then group
+	 * @param $groupLoads
+	 * @return array
 	 */
 	function reindexGroupLoads( $groupLoads ) {
 		$reindexed = array();
@@ -233,6 +242,8 @@ class LBFactory_Multi extends LBFactory {
 
 	/**
 	 * Get the database name and prefix based on the wiki ID
+	 * @param bool $wiki
+	 * @return array
 	 */
 	function getDBNameAndPrefix( $wiki = false ) {
 		if ( $wiki === false ) {
@@ -247,6 +258,8 @@ class LBFactory_Multi extends LBFactory {
 	 * Execute a function for each tracked load balancer
 	 * The callback is called with the load balancer as the first parameter,
 	 * and $params passed as the subsequent parameters.
+	 * @param $callback
+	 * @param $params array
 	 */
 	function forEachLB( $callback, $params = array() ) {
 		foreach ( $this->mainLBs as $lb ) {
diff --git a/includes/db/LBFactory_Single.php b/includes/db/LBFactory_Single.php
index 89b41321f1..f80aa4bc2f 100644
--- a/includes/db/LBFactory_Single.php
+++ b/includes/db/LBFactory_Single.php
@@ -15,7 +15,7 @@ class LBFactory_Single extends LBFactory {
 	}
 
 	/**
-	 * @param $wiki
+	 * @param $wiki bool|string
 	 *
 	 * @return LoadBalancer_Single
 	 */
@@ -24,7 +24,7 @@ class LBFactory_Single extends LBFactory {
 	}
 
 	/**
-	 * @param $wiki
+	 * @param $wiki bool|string
 	 *
 	 * @return LoadBalancer_Single
 	 */
@@ -34,7 +34,7 @@ class LBFactory_Single extends LBFactory {
 
 	/**
 	 * @param $cluster
-	 * @param $wiki
+	 * @param $wiki bool|string
 	 *
 	 * @return LoadBalancer_Single
 	 */
@@ -44,7 +44,7 @@ class LBFactory_Single extends LBFactory {
 
 	/**
 	 * @param $cluster
-	 * @param $wiki
+	 * @param $wiki bool|string
 	 *
 	 * @return LoadBalancer_Single
 	 */
diff --git a/includes/db/LoadBalancer.php b/includes/db/LoadBalancer.php
index 891368b315..cabda93e74 100644
--- a/includes/db/LoadBalancer.php
+++ b/includes/db/LoadBalancer.php
@@ -391,6 +391,9 @@ class LoadBalancer {
 
 	/**
 	 * Wait for a given slave to catch up to the master pos stored in $this
+	 * @param $index
+	 * @param $open bool
+	 * @return bool
 	 */
 	function doWait( $index, $open = false ) {
 		# Find a connection to wait on
@@ -668,7 +671,7 @@ class LoadBalancer {
 	function reallyOpenConnection( $server, $dbNameOverride = false ) {
 		if( !is_array( $server ) ) {
 			throw new MWException( 'You must update your load-balancing configuration. ' .
-			                       'See DefaultSettings.php entry for $wgDBservers.' );
+				'See DefaultSettings.php entry for $wgDBservers.' );
 		}
 
 		$host = $server['host'];
@@ -837,8 +840,7 @@ class LoadBalancer {
 	 * Close a connection
 	 * Using this function makes sure the LoadBalancer knows the connection is closed.
 	 * If you use $conn->close() directly, the load balancer won't update its state.
-	 * @param $conn
-	 * @return void
+	 * @param $conn DatabaseBase
 	 */
 	function closeConnection( $conn ) {
 		$done = false;
@@ -890,10 +892,17 @@ class LoadBalancer {
 		}
 	}
 
+	/**
+	 * @param $value null
+	 * @return Mixed
+	 */
 	function waitTimeout( $value = null ) {
 		return wfSetVar( $this->mWaitTimeout, $value );
 	}
 
+	/**
+	 * @return bool
+	 */
 	function getLaggedSlaveMode() {
 		return $this->mLaggedSlaveMode;
 	}
@@ -906,6 +915,9 @@ class LoadBalancer {
 		$this->mAllowLagged = $mode;
 	}
 
+	/**
+	 * @return bool
+	 */
 	function pingAll() {
 		$success = true;
 		foreach ( $this->mConns as $conns2 ) {
@@ -1005,6 +1017,10 @@ class LoadBalancer {
 	 * potentially restricted queries such as SHOW SLAVE STATUS. Using this
 	 * function instead of Database::getLag() avoids a fatal error in this
 	 * case on many installations.
+	 *
+	 * @param $conn DatabaseBase
+	 *
+	 * @return int
 	 */
 	function safeGetLag( $conn ) {
 		if ( $this->getServerCount() == 1 ) {