r44044 MediaWiki - Code Review archive

Repository:	MediaWiki
Revision:	< r44043‎ \| r44044 \| r44045 >
Date:	18:50, 29 November 2008
Author:	ialex
Status:	ok
Tags:
Comment:	* fixed Doxygen errors in Database.php, DatabasePostgres.php, DatabaseOracle.php and DatabaseMssql.php * renamed \2types and \3types both to \types (with different number of param), Doxygen doesn't seem to like numbers in aliases * Added aliases for @private, @protected and @public
Modified paths:	/trunk/phase3/includes/User.php (modified) (history) /trunk/phase3/includes/db/Database.php (modified) (history) /trunk/phase3/includes/db/DatabaseMssql.php (modified) (history) /trunk/phase3/includes/db/DatabaseOracle.php (modified) (history) /trunk/phase3/includes/db/DatabasePostgres.php (modified) (history) /trunk/phase3/maintenance/Doxyfile (modified) (history)

Diff [purge]

Index: trunk/phase3/maintenance/Doxyfile
—	—	@@ -279,8 +279,8 @@
280	280	SEARCHENGINE = NO
281	281
282	282	ALIASES = "type{1}=<b> \1 </b>:" \
283		~~- "2types{2}=<b> \1 </b> or <b> \2 </b>:" \~~
284		~~- "3types{3}=<b> \1 </b>, <b> \2 </b>, or <b> \3 </b>:" \~~
	283	+ "types{2}=<b> \1 </b> or <b> \2 </b>:" \
	284	+ "types{3}=<b> \1 </b>, <b> \2 </b>, or <b> \3 </b>:" \
285	285	"arrayof{2}=<b> Array </b> of \2" \
286	286	"null=\type{Null}" \
287	287	"boolean=\type{Boolean}" \
—	—	@@ -289,4 +289,8 @@
290	290	"int=\integer" \
291	291	"string=\type{String}" \
292	292	"str=\string" \
293		~~- "mixed=\type{Mixed}"~~
\ No newline at end of file
	293	+ "mixed=\type{Mixed}" \
	294	+ "access=\n<b> Access </b>:\n" \
	295	+ "private=\access private" \
	296	+ "protected=\access protected" \
	297	+ "public=\access public"
\ No newline at end of file
Index: trunk/phase3/includes/db/DatabaseOracle.php
—	—	@@ -509,10 +509,10 @@
510	510	* Returns an SQL expression for a simple conditional.
511	511	* Uses CASE on Oracle
512	512	*
513		~~- * @param string $cond SQL expression which will result in a boolean value~~
514		~~- * @param string $trueVal SQL expression to return if true~~
515		~~- * @param string $falseVal SQL expression to return if false~~
516		~~- * @return string SQL fragment~~
	513	+ * @param $cond String: SQL expression which will result in a boolean value
	514	+ * @param $trueVal String: SQL expression to return if true
	515	+ * @param $falseVal String: SQL expression to return if false
	516	+ * @return String: SQL fragment
517	517	*/
518	518	function conditional( $cond, $trueVal, $falseVal ) {
519	519	return " (CASE WHEN $cond THEN $trueVal ELSE $falseVal END) ";
—	—	@@ -640,7 +640,7 @@
641	641	*
642	642	* @private
643	643	*
644		~~- * @param array $options an associative array of options to be turned into~~
	644	+ * @param $options Array: an associative array of options to be turned into
645	645	* an SQL query, valid keys are listed in the function.
646	646	* @return array
647	647	*/
Index: trunk/phase3/includes/db/DatabasePostgres.php
—	—	@@ -723,10 +723,10 @@
724	724	* $args may be a single associative array, or an array of these with numeric keys,
725	725	* for multi-row insert (Postgres version 8.2 and above only).
726	726	*
727		~~- * @param array $table String: Name of the table to insert to.~~
728		~~- * @param array $args Array: Items to insert into the table.~~
729		~~- * @param array $fname String: Name of the function, for profiling~~
730		~~- * @param mixed $options String or Array. Valid options: IGNORE~~
	727	+ * @param $table String: Name of the table to insert to.
	728	+ * @param $args Array: Items to insert into the table.
	729	+ * @param $fname String: Name of the function, for profiling
	730	+ * @param $options String or Array. Valid options: IGNORE
731	731	*
732	732	* @return bool Success of insert operation. IGNORE always returns true.
733	733	*/
—	—	@@ -1001,10 +1001,10 @@
1002	1002	* Returns an SQL expression for a simple conditional.
1003	1003	* Uses CASE on Postgres
1004	1004	*
1005		~~- * @param string $cond SQL expression which will result in a boolean value~~
1006		~~- * @param string $trueVal SQL expression to return if true~~
1007		~~- * @param string $falseVal SQL expression to return if false~~
1008		~~- * @return string SQL fragment~~
	1005	+ * @param $cond String: SQL expression which will result in a boolean value
	1006	+ * @param $trueVal String: SQL expression to return if true
	1007	+ * @param $falseVal String: SQL expression to return if false
	1008	+ * @return String: SQL fragment
1009	1009	*/
1010	1010	function conditional( $cond, $trueVal, $falseVal ) {
1011	1011	return " (CASE WHEN $cond THEN $trueVal ELSE $falseVal END) ";
—	—	@@ -1305,7 +1305,7 @@
1306	1306	*
1307	1307	* @private
1308	1308	*
1309		~~- * @param string $com SQL string, read from a stream (usually tables.sql)~~
	1309	+ * @param $ins String: SQL string, read from a stream (usually tables.sql)
1310	1310	*
1311	1311	* @return string SQL string
1312	1312	*/
—	—	@@ -1330,7 +1330,7 @@
1331	1331	*
1332	1332	* @private
1333	1333	*
1334		~~- * @param array $options an associative array of options to be turned into~~
	1334	+ * @param $options Array: an associative array of options to be turned into
1335	1335	* an SQL query, valid keys are listed in the function.
1336	1336	* @return array
1337	1337	*/
Index: trunk/phase3/includes/db/Database.php
—	—	@@ -207,13 +207,13 @@
208	208
209	209	/**
210	210	* Return the last query that went through Database::query()
211		~~- * @return string~~
	211	+ * @return String
212	212	*/
213	213	function lastQuery() { return $this->mLastQuery; }
214	214
215	215	/**
216	216	* Is a connection to the database open?
217		~~- * @return bool~~
	217	+ * @return Boolean
218	218	*/
219	219	function isOpen() { return $this->mOpened; }
220	220
—	—	@@ -248,13 +248,13 @@
249	249	# Other functions
250	250	#------------------------------------------------------------------------------
251	251
252		~~- /**@{{~~
	252	+ /**
253	253	* Constructor.
254		~~- * @param string $server database server host~~
255		~~- * @param string $user database user name~~
256		~~- * @param string $password database user password~~
257		~~- * @param string $dbname database name~~
258		~~- * @param failFunction~~
	254	+ * @param $server String: database server host
	255	+ * @param $user String: database user name
	256	+ * @param $password String: database user password
	257	+ * @param $dbName String: database name
	258	+ * @param $failFunction
259	259	* @param $flags
260	260	* @param $tablePrefix String: database table prefixes. By default use the prefix gave in LocalSettings.php
261	261	*/
—	—	@@ -298,7 +298,11 @@
299	299	}
300	300
301	301	/**
302		~~- * @static~~
	302	+ * Same as new Database( ... ), kept for backward compatibility
	303	+ * @param $server String: database server host
	304	+ * @param $user String: database user name
	305	+ * @param $password String: database user password
	306	+ * @param $dbName String: database name
303	307	* @param failFunction
304	308	* @param $flags
305	309	*/
—	—	@@ -310,6 +314,10 @@
311	315	/**
312	316	* Usually aborts on failure
313	317	* If the failFunction is set to a non-zero integer, returns success
	318	+ * @param $server String: database server host
	319	+ * @param $user String: database user name
	320	+ * @param $password String: database user password
	321	+ * @param $dbName String: database name
314	322	*/
315	323	function open( $server, $user, $password, $dbName ) {
316	324	global $wgAllDBsAreLocalhost;
—	—	@@ -419,7 +427,6 @@
420	428	wfProfileOut( __METHOD__ );
421	429	return $success;
422	430	}
423		~~- /*@}}/~~
424	431
425	432	protected function installErrorHandler() {
426	433	$this->mPHPError = false;
—	—	@@ -449,7 +456,7 @@
450	457	* Closes a database connection.
451	458	* if it is open : commits any open transactions
452	459	*
453		~~- * @return bool operation success. true if already closed.~~
	460	+ * @return Bool operation success. true if already closed.
454	461	*/
455	462	function close()
456	463	{
—	—	@@ -465,7 +472,7 @@
466	473	}
467	474
468	475	/**
469		~~- * @param string $error fallback error message, used if none is given by MySQL~~
	476	+ * @param $error String: fallback error message, used if none is given by MySQL
470	477	*/
471	478	function reportConnectionError( $error = 'Unknown error' ) {
472	479	$myError = $this->lastError();
—	—	@@ -491,7 +498,7 @@
492	499	* @param $sql String: SQL query
493	500	* @param $fname String: Name of the calling function, for profiling/SHOW PROCESSLIST
494	501	* comment (you can use __METHOD__ or add some extra info)
495		~~- * @param $tempIgnore Bool: Whether to avoid throwing an exception on errors...~~
	502	+ * @param $tempIgnore Boolean: Whether to avoid throwing an exception on errors...
496	503	* maybe best to catch the exception instead?
497	504	* @return true for a successful write query, ResultWrapper object for a successful read query,
498	505	* or false on failure if $tempIgnore set
—	—	@@ -595,7 +602,7 @@
596	603	* The DBMS-dependent part of query()
597	604	* @param $sql String: SQL query.
598	605	* @return Result object to feed to fetchObject, fetchRow, ...; or false on failure
599		~~- * @access private~~
	606	+ * @private
600	607	*/
601	608	/private/ function doQuery( $sql ) {
602	609	if( $this->bufferResults() ) {
—	—	@@ -607,11 +614,11 @@
608	615	}
609	616
610	617	/**
611		~~- * @param $error~~
612		~~- * @param $errno~~
613		~~- * @param $sql~~
614		~~- * @param string $fname~~
615		~~- * @param bool $tempIgnore~~
	618	+ * @param $error String
	619	+ * @param $errno Integer
	620	+ * @param $sql String
	621	+ * @param $fname String
	622	+ * @param $tempIgnore Boolean
616	623	*/
617	624	function reportQueryError( $error, $errno, $sql, $fname, $tempIgnore = false ) {
618	625	global $wgCommandLineMode;
—	—	@@ -653,8 +660,8 @@
654	661
655	662	/**
656	663	* Execute a prepared query with the various arguments
657		~~- * @param string $prepared the prepared sql~~
658		~~- * @param mixed $args Either an array here, or put scalars as varargs~~
	664	+ * @param $prepared String: the prepared sql
	665	+ * @param $args Mixed: Either an array here, or put scalars as varargs
659	666	*/
660	667	function execute( $prepared, $args = null ) {
661	668	if( !is_array( $args ) ) {
—	—	@@ -669,8 +676,8 @@
670	677	/**
671	678	* Prepare & execute an SQL statement, quoting and inserting arguments
672	679	* in the appropriate places.
673		~~- * @param string $query~~
674		~~- * @param string $args ...~~
	680	+ * @param $query String
	681	+ * @param $args ...
675	682	*/
676	683	function safeQuery( $query, $args = null ) {
677	684	$prepared = $this->prepare( $query, 'Database::safeQuery' );
—	—	@@ -687,8 +694,8 @@
688	695	/**
689	696	* For faking prepared SQL statements on DBs that don't support
690	697	* it directly.
691		~~- * @param string $preparedSql - a 'preparable' SQL statement~~
692		~~- * @param array $args - array of arguments to fill it with~~
	698	+ * @param $preparedQuery String: a 'preparable' SQL statement
	699	+ * @param $args Array of arguments to fill it with
693	700	* @return string executable SQL
694	701	*/
695	702	function fillPrepared( $preparedQuery, $args ) {
—	—	@@ -703,8 +710,8 @@
704	711	* The arguments should be in $this->preparedArgs and must not be touched
705	712	* while we're doing this.
706	713	*
707		~~- * @param array $matches~~
708		~~- * @return string~~
	714	+ * @param $matches Array
	715	+ * @return String
709	716	* @private
710	717	*/
711	718	function fillPreparedArg( $matches ) {
—	—	@@ -725,11 +732,9 @@
726	733	}
727	734	}
728	735
729		~~- /**#@+~~
730		~~- * @param mixed $res A SQL result~~
731		~~- */~~
732	736	/**
733	737	* Free a result object
	738	+ * @param $res Mixed: A SQL result
734	739	*/
735	740	function freeResult( $res ) {
736	741	if ( $res instanceof ResultWrapper ) {
—	—	@@ -781,6 +786,7 @@
782	787
783	788	/**
784	789	* Get the number of rows in a result object
	790	+ * @param $res Mixed: A SQL result
785	791	*/
786	792	function numRows( $res ) {
787	793	if ( $res instanceof ResultWrapper ) {
—	—	@@ -796,6 +802,7 @@
797	803	/**
798	804	* Get the number of fields in a result object
799	805	* See documentation for mysql_num_fields()
	806	+ * @param $res Mixed: A SQL result
800	807	*/
801	808	function numFields( $res ) {
802	809	if ( $res instanceof ResultWrapper ) {
—	—	@@ -808,6 +815,8 @@
809	816	* Get a field name in a result object
810	817	* See documentation for mysql_field_name():
811	818	* http://www.php.net/mysql_field_name
	819	+ * @param $res Mixed: A SQL result
	820	+ * @param $n Integer
812	821	*/
813	822	function fieldName( $res, $n ) {
814	823	if ( $res instanceof ResultWrapper ) {
—	—	@@ -831,6 +840,8 @@
832	841	/**
833	842	* Change the position of the cursor in a result object
834	843	* See mysql_data_seek()
	844	+ * @param $res Mixed: A SQL result
	845	+ * @param $row Mixed: Either MySQL row or ResultWrapper
835	846	*/
836	847	function dataSeek( $res, $row ) {
837	848	if ( $res instanceof ResultWrapper ) {
—	—	@@ -877,7 +888,6 @@
878	889	* See mysql_affected_rows() for more details
879	890	*/
880	891	function affectedRows() { return mysql_affected_rows( $this->mConn ); }
881		~~- /*#@-/ // end of template : @param $result~~
882	892
883	893	/**
884	894	* Simple UPDATE wrapper
—	—	@@ -887,8 +897,7 @@
888	898	* This function exists for historical reasons, Database::update() has a more standard
889	899	* calling convention and feature set
890	900	*/
891		~~- function set( $table, $var, $value, $cond, $fname = 'Database::set' )~~
892		~~- {~~
	901	+ function set( $table, $var, $value, $cond, $fname = 'Database::set' ) {
893	902	$table = $this->tableName( $table );
894	903	$sql = "UPDATE $table SET $var = '" .
895	904	$this->strencode( $value ) . "' WHERE ($cond)";
—	—	@@ -925,9 +934,9 @@
926	935	*
927	936	* @private
928	937	*
929		~~- * @param array $options an associative array of options to be turned into~~
	938	+ * @param $options Array: associative array of options to be turned into
930	939	* an SQL query, valid keys are listed in the function.
931		~~- * @return array~~
	940	+ * @return Array
932	941	*/
933	942	function makeSelectOptions( $options ) {
934	943	$preLimitTail = $postLimitTail = '';
—	—	@@ -976,14 +985,14 @@
977	986	/**
978	987	* SELECT wrapper
979	988	*
980		~~- * @param mixed $table Array or string, table name(s) (prefix auto-added)~~
981		~~- * @param mixed $vars Array or string, field name(s) to be retrieved~~
982		~~- * @param mixed $conds Array or string, condition(s) for WHERE~~
983		~~- * @param string $fname Calling function name (use __METHOD__) for logs/profiling~~
984		~~- * @param array $options Associative array of options (e.g. array('GROUP BY' => 'page_title')),~~
985		~~- * see Database::makeSelectOptions code for list of supported stuff~~
986		~~- * @param array $join_conds Associative array of table join conditions (optional)~~
987		~~- * (e.g. array( 'page' => array('LEFT JOIN','page_latest=rev_id') )~~
	989	+ * @param $table Mixed: Array or string, table name(s) (prefix auto-added)
	990	+ * @param $vars Mixed: Array or string, field name(s) to be retrieved
	991	+ * @param $conds Mixed: Array or string, condition(s) for WHERE
	992	+ * @param $fname String: Calling function name (use __METHOD__) for logs/profiling
	993	+ * @param $options Array: Associative array of options (e.g. array('GROUP BY' => 'page_title')),
	994	+ * see Database::makeSelectOptions code for list of supported stuff
	995	+ * @param $join_conds Array: Associative array of table join conditions (optional)
	996	+ * (e.g. array( 'page' => array('LEFT JOIN','page_latest=rev_id') )
988	997	* @return mixed Database result resource (feed to Database::fetchObject or whatever), or false on failure
989	998	*/
990	999	function select( $table, $vars, $conds='', $fname = 'Database::select', $options = array(), $join_conds = array() )
—	—	@@ -995,14 +1004,14 @@
996	1005	/**
997	1006	* SELECT wrapper
998	1007	*
999		~~- * @param mixed $table Array or string, table name(s) (prefix auto-added)~~
1000		~~- * @param mixed $vars Array or string, field name(s) to be retrieved~~
1001		~~- * @param mixed $conds Array or string, condition(s) for WHERE~~
1002		~~- * @param string $fname Calling function name (use __METHOD__) for logs/profiling~~
1003		~~- * @param array $options Associative array of options (e.g. array('GROUP BY' => 'page_title')),~~
1004		~~- * see Database::makeSelectOptions code for list of supported stuff~~
1005		~~- * @param array $join_conds Associative array of table join conditions (optional)~~
1006		~~- * (e.g. array( 'page' => array('LEFT JOIN','page_latest=rev_id') )~~
	1008	+ * @param $table Mixed: Array or string, table name(s) (prefix auto-added)
	1009	+ * @param $vars Mixed: Array or string, field name(s) to be retrieved
	1010	+ * @param $conds Mixed: Array or string, condition(s) for WHERE
	1011	+ * @param $fname String: Calling function name (use __METHOD__) for logs/profiling
	1012	+ * @param $options Array: Associative array of options (e.g. array('GROUP BY' => 'page_title')),
	1013	+ * see Database::makeSelectOptions code for list of supported stuff
	1014	+ * @param $join_conds Array: Associative array of table join conditions (optional)
	1015	+ * (e.g. array( 'page' => array('LEFT JOIN','page_latest=rev_id') )
1007	1016	* @return string, the SQL text
1008	1017	*/
1009	1018	function selectSQLText( $table, $vars, $conds='', $fname = 'Database::select', $options = array(), $join_conds = array() ) {
—	—	@@ -1053,13 +1062,17 @@
1054	1063	* Single row SELECT wrapper
1055	1064	* Aborts or returns FALSE on error
1056	1065	*
1057		~~- * $vars: the selected variables~~
1058		~~- * $conds: a condition map, terms are ANDed together.~~
	1066	+ * @param $table String: table name
	1067	+ * @param $vars String: the selected variables
	1068	+ * @param $conds Array: a condition map, terms are ANDed together.
1059	1069	* Items with numeric keys are taken to be literal conditions
1060	1070	* Takes an array of selected variables, and a condition map, which is ANDed
1061	1071	* e.g: selectRow( "page", array( "page_id" ), array( "page_namespace" =>
1062	1072	* NS_MAIN, "page_title" => "Astronomy" ) ) would return an object where
1063	1073	* $obj- >page_id is the ID of the Astronomy article
	1074	+ * @param $fname String: Calling functio name
	1075	+ * @param $options Array
	1076	+ * @param $join_conds Array
1064	1077	*
1065	1078	* @todo migrate documentation to phpdocumentor format
1066	1079	*/
—	—	@@ -1109,8 +1122,7 @@
1110	1123	* Removes most variables from an SQL query and replaces them with X or N for numbers.
1111	1124	* It's only slightly flawed. Don't use for anything important.
1112	1125	*
1113		~~- * @param string $sql A SQL Query~~
1114		~~- * @static~~
	1126	+ * @param $sql String: A SQL Query
1115	1127	*/
1116	1128	static function generalizeSQL( $sql ) {
1117	1129	# This does the same as the regexp below would do, but in such a way
—	—	@@ -1303,7 +1315,7 @@
1304	1316	* Make UPDATE options for the Database::update function
1305	1317	*
1306	1318	* @private
1307		~~- * @param array $options The options passed to Database::update~~
	1319	+ * @param $options Array: The options passed to Database::update
1308	1320	* @return string
1309	1321	*/
1310	1322	function makeUpdateOptions( $options ) {
—	—	@@ -1321,14 +1333,14 @@
1322	1334	/**
1323	1335	* UPDATE wrapper, takes a condition array and a SET array
1324	1336	*
1325		~~- * @param string $table The table to UPDATE~~
1326		~~- * @param array $values An array of values to SET~~
1327		~~- * @param array $conds An array of conditions (WHERE). Use '*' to update all rows.~~
1328		~~- * @param string $fname The Class::Function calling this function~~
1329		~~- * (for the log)~~
1330		~~- * @param array $options An array of UPDATE options, can be one or~~
	1337	+ * @param $table String: The table to UPDATE
	1338	+ * @param $values Array: An array of values to SET
	1339	+ * @param $conds Array: An array of conditions (WHERE). Use '*' to update all rows.
	1340	+ * @param $fname String: The Class::Function calling this function
	1341	+ * (for the log)
	1342	+ * @param $options Array: An array of UPDATE options, can be one or
1331	1343	* more of IGNORE, LOW_PRIORITY
1332		~~- * @return bool~~
	1344	+ * @return Boolean
1333	1345	*/
1334	1346	function update( $table, $values, $conds, $fname = 'Database::update', $options = array() ) {
1335	1347	$table = $this->tableName( $table );
—	—	@@ -1433,8 +1445,8 @@
1434	1446	* themselves. Pass the canonical name to such functions. This is only needed
1435	1447	* when calling query() directly.
1436	1448	*
1437		~~- * @param string $name database table name~~
1438		~~- * @return string full database name~~
	1449	+ * @param $name String: database table name
	1450	+ * @return String: full database name
1439	1451	*/
1440	1452	function tableName( $name ) {
1441	1453	global $wgSharedDB, $wgSharedPrefix, $wgSharedTables;
—	—	@@ -1563,8 +1575,8 @@
1564	1576
1565	1577	/**
1566	1578	* Wrapper for addslashes()
1567		~~- * @param string $s String to be slashed.~~
1568		~~- * @return string slashed string.~~
	1579	+ * @param $s String: to be slashed.
	1580	+ * @return String: slashed string.
1569	1581	*/
1570	1582	function strencode( $s ) {
1571	1583	return mysql_real_escape_string( $s, $this->mConn );
—	—	@@ -1655,11 +1667,12 @@
1656	1668	*
1657	1669	* DO NOT put the join condition in $conds
1658	1670	*
1659		~~- * @param string $delTable The table to delete from.~~
1660		~~- * @param string $joinTable The other table.~~
1661		~~- * @param string $delVar The variable to join on, in the first table.~~
1662		~~- * @param string $joinVar The variable to join on, in the second table.~~
1663		~~- * @param array $conds Condition array of field names mapped to variables, ANDed together in the WHERE clause~~
	1671	+ * @param $delTable String: The table to delete from.
	1672	+ * @param $joinTable String: The other table.
	1673	+ * @param $delVar String: The variable to join on, in the first table.
	1674	+ * @param $joinVar String: The variable to join on, in the second table.
	1675	+ * @param $conds Array: Condition array of field names mapped to variables, ANDed together in the WHERE clause
	1676	+ * @param $fname String: Calling function name (use __METHOD__) for logs/profiling
1664	1677	*/
1665	1678	function deleteJoin( $delTable, $joinTable, $delVar, $joinVar, $conds, $fname = 'Database::deleteJoin' ) {
1666	1679	if ( !$conds ) {
—	—	@@ -1755,9 +1768,9 @@
1756	1769	/**
1757	1770	* Construct a LIMIT query with optional offset
1758	1771	* This is used for query pages
1759		~~- * $sql string SQL query we will append the limit too~~
1760		~~- * $limit integer the SQL limit~~
1761		~~- * $offset integer the SQL offset (default false)~~
	1772	+ * @param $sql String: SQL query we will append the limit too
	1773	+ * @param $limit Integer: the SQL limit
	1774	+ * @param $offset Integer the SQL offset (default false)
1762	1775	*/
1763	1776	function limitResult($sql, $limit, $offset=false) {
1764	1777	if( !is_numeric($limit) ) {
—	—	@@ -1775,10 +1788,10 @@
1776	1789	* Returns an SQL expression for a simple conditional.
1777	1790	* Uses IF on MySQL.
1778	1791	*
1779		~~- * @param string $cond SQL expression which will result in a boolean value~~
1780		~~- * @param string $trueVal SQL expression to return if true~~
1781		~~- * @param string $falseVal SQL expression to return if false~~
1782		~~- * @return string SQL fragment~~
	1792	+ * @param $cond String: SQL expression which will result in a boolean value
	1793	+ * @param $trueVal String: SQL expression to return if true
	1794	+ * @param $falseVal String: SQL expression to return if false
	1795	+ * @return String: SQL fragment
1783	1796	*/
1784	1797	function conditional( $cond, $trueVal, $falseVal ) {
1785	1798	return " IF($cond, $trueVal, $falseVal) ";
—	—	@@ -1788,9 +1801,9 @@
1789	1802	* Returns a comand for str_replace function in SQL query.
1790	1803	* Uses REPLACE() in MySQL
1791	1804	*
1792		~~- * @param string $orig String or column to modify~~
1793		~~- * @param string $old String or column to seek~~
1794		~~- * @param string $new String or column to replace with~~
	1805	+ * @param $orig String: column to modify
	1806	+ * @param $old String: column to seek
	1807	+ * @param $new String: column to replace with
1795	1808	*/
1796	1809	function strreplace( $orig, $old, $new ) {
1797	1810	return "REPLACE({$orig}, {$old}, {$new})";
—	—	@@ -1861,9 +1874,8 @@
1862	1875	/**
1863	1876	* Do a SELECT MASTER_POS_WAIT()
1864	1877	*
1865		~~- * @param string $file the binlog file~~
1866		~~- * @param string $pos the binlog position~~
1867		~~- * @param integer $timeout the maximum number of seconds to wait for synchronisation~~
	1878	+ * @param $pos MySQLMasterPos object
	1879	+ * @param $timeout Integer: the maximum number of seconds to wait for synchronisation
1868	1880	*/
1869	1881	function masterPosWait( MySQLMasterPos $pos, $timeout ) {
1870	1882	$fname = 'Database::masterPosWait';
—	—	@@ -2024,14 +2036,14 @@
2025	2037	}
2026	2038
2027	2039	/**
2028		~~- * @return string wikitext of a link to the server software's web site~~
	2040	+ * @return String: wikitext of a link to the server software's web site
2029	2041	*/
2030	2042	function getSoftwareLink() {
2031	2043	return "[http://www.mysql.com/ MySQL]";
2032	2044	}
2033	2045
2034	2046	/**
2035		~~- * @return string Version information from the database~~
	2047	+ * @return String: Version information from the database
2036	2048	*/
2037	2049	function getServerVersion() {
2038	2050	return mysql_get_server_info( $this->mConn );
—	—	@@ -2129,7 +2141,7 @@
2130	2142	* May be useful for very long batch queries such as
2131	2143	* full-wiki dumps, where a single query reads out
2132	2144	* over hours or days.
2133		~~- * @param int $timeout in seconds~~
	2145	+ * @param $timeout Integer in seconds
2134	2146	*/
2135	2147	public function setTimeout( $timeout ) {
2136	2148	$this->query( "SET net_read_timeout=$timeout" );
—	—	@@ -2139,9 +2151,9 @@
2140	2152	/**
2141	2153	* Read and execute SQL commands from a file.
2142	2154	* Returns true on success, error string or exception on failure (depending on object's error ignore settings)
2143		~~- * @param string $filename File name to open~~
2144		~~- * @param callback $lineCallback Optional function called before reading each line~~
2145		~~- * @param callback $resultCallback Optional function called for each MySQL result~~
	2155	+ * @param $filename String: File name to open
	2156	+ * @param $lineCallback Callback: Optional function called before reading each line
	2157	+ * @param $resultCallback Callback: Optional function called for each MySQL result
2146	2158	*/
2147	2159	function sourceFile( $filename, $lineCallback = false, $resultCallback = false ) {
2148	2160	$fp = fopen( $filename, 'r' );
—	—	@@ -2156,9 +2168,9 @@
2157	2169	/**
2158	2170	* Read and execute commands from an open file handle
2159	2171	* Returns true on success, error string or exception on failure (depending on object's error ignore settings)
2160		~~- * @param string $fp File handle~~
2161		~~- * @param callback $lineCallback Optional function called before reading each line~~
2162		~~- * @param callback $resultCallback Optional function called for each MySQL result~~
	2172	+ * @param $fp String: File handle
	2173	+ * @param $lineCallback Callback: Optional function called before reading each line
	2174	+ * @param $resultCallback Callback: Optional function called for each MySQL result
2163	2175	*/
2164	2176	function sourceStream( $fp, $lineCallback = false, $resultCallback = false ) {
2165	2177	$cmd = "";
—	—	@@ -2263,8 +2275,8 @@
2264	2276	* Abstracted from Filestore::lock() so child classes can implement for
2265	2277	* their own needs.
2266	2278	*
2267		~~- * @param string $lockName Name of lock to aquire~~
2268		~~- * @param string $method Name of method calling us~~
	2279	+ * @param $lockName String: Name of lock to aquire
	2280	+ * @param $method String: Name of method calling us
2269	2281	* @return bool
2270	2282	*/
2271	2283	public function lock( $lockName, $method ) {
—	—	@@ -2286,8 +2298,8 @@
2287	2299	* @todo fixme - Figure out a way to return a bool
2288	2300	* based on successful lock release.
2289	2301	*
2290		~~- * @param string $lockName Name of lock to release~~
2291		~~- * @param string $method Name of method calling us~~
	2302	+ * @param $lockName String: Name of lock to release
	2303	+ * @param $method String: Name of method calling us
2292	2304	*/
2293	2305	public function unlock( $lockName, $method ) {
2294	2306	$lockName = $this->addQuotes( $lockName );
—	—	@@ -2299,7 +2311,7 @@
2300	2312	* Get search engine class. All subclasses of this
2301	2313	* need to implement this if they wish to use searching.
2302	2314	*
2303		~~- * @return string~~
	2315	+ * @return String
2304	2316	*/
2305	2317	public function getSearchEngine() {
2306	2318	return "SearchMySQL";
—	—	@@ -2423,8 +2435,8 @@
2424	2436
2425	2437	/**
2426	2438	* Construct a database error
2427		~~- * @param Database $db The database object which threw the error~~
2428		~~- * @param string $error A simple error message to be used for debugging~~
	2439	+ * @param $db Database object which threw the error
	2440	+ * @param $error A simple error message to be used for debugging
2429	2441	*/
2430	2442	function __construct( Database &$db, $error ) {
2431	2443	$this->db =& $db;
Index: trunk/phase3/includes/db/DatabaseMssql.php
—	—	@@ -154,9 +154,6 @@
155	155	return $ret;
156	156	}
157	157
158		~~- /**#@+~~
159		~~- * @param mixed $res A SQL result~~
160		~~- */~~
161	158	/**
162	159	* Free a result object
163	160	*/
—	—	@@ -225,6 +222,7 @@
226	223	/**
227	224	* Get the number of fields in a result object
228	225	* See documentation for mysql_num_fields()
	226	+ * @param $res SQL result object as returned from Database::query(), etc.
229	227	*/
230	228	function numFields( $res ) {
231	229	if ( $res instanceof ResultWrapper ) {
—	—	@@ -237,6 +235,8 @@
238	236	* Get a field name in a result object
239	237	* See documentation for mysql_field_name():
240	238	* http://www.php.net/mysql_field_name
	239	+ * @param $res SQL result object as returned from Database::query(), etc.
	240	+ * @param $n Int
241	241	*/
242	242	function fieldName( $res, $n ) {
243	243	if ( $res instanceof ResultWrapper ) {
—	—	@@ -263,6 +263,8 @@
264	264	/**
265	265	* Change the position of the cursor in a result object
266	266	* See mysql_data_seek()
	267	+ * @param $res SQL result object as returned from Database::query(), etc.
	268	+ * @param $row Database row
267	269	*/
268	270	function dataSeek( $res, $row ) {
269	271	if ( $res instanceof ResultWrapper ) {
—	—	@@ -339,7 +341,7 @@
340	342	*
341	343	* @private
342	344	*
343		~~- * @param array $options an associative array of options to be turned into~~
	345	+ * @param $options Array: an associative array of options to be turned into
344	346	* an SQL query, valid keys are listed in the function.
345	347	* @return array
346	348	*/
—	—	@@ -390,11 +392,11 @@
391	393	/**
392	394	* SELECT wrapper
393	395	*
394		~~- * @param mixed $table Array or string, table name(s) (prefix auto-added)~~
395		~~- * @param mixed $vars Array or string, field name(s) to be retrieved~~
396		~~- * @param mixed $conds Array or string, condition(s) for WHERE~~
397		~~- * @param string $fname Calling function name (use __METHOD__) for logs/profiling~~
398		~~- * @param array $options Associative array of options (e.g. array('GROUP BY' => 'page_title')),~~
	396	+ * @param $table Mixed: Array or string, table name(s) (prefix auto-added)
	397	+ * @param $vars Mixed: Array or string, field name(s) to be retrieved
	398	+ * @param $conds Mixed: Array or string, condition(s) for WHERE
	399	+ * @param $fname String: Calling function name (use __METHOD__) for logs/profiling
	400	+ * @param $options Array: Associative array of options (e.g. array('GROUP BY' => 'page_title')),
399	401	* see Database::makeSelectOptions code for list of supported stuff
400	402	* @return mixed Database result resource (feed to Database::fetchObject or whatever), or false on failure
401	403	*/
—	—	@@ -643,12 +645,12 @@
644	646	/**
645	647	* UPDATE wrapper, takes a condition array and a SET array
646	648	*
647		~~- * @param string $table The table to UPDATE~~
648		~~- * @param array $values An array of values to SET~~
649		~~- * @param array $conds An array of conditions (WHERE). Use '*' to update all rows.~~
650		~~- * @param string $fname The Class::Function calling this function~~
651		~~- * (for the log)~~
652		~~- * @param array $options An array of UPDATE options, can be one or~~
	649	+ * @param $table String: The table to UPDATE
	650	+ * @param $values Array: An array of values to SET
	651	+ * @param $conds Array: An array of conditions (WHERE). Use '*' to update all rows.
	652	+ * @param $fname String: The Class::Function calling this function
	653	+ * (for the log)
	654	+ * @param $options Array: An array of UPDATE options, can be one or
653	655	* more of IGNORE, LOW_PRIORITY
654	656	* @return bool
655	657	*/
—	—	@@ -666,7 +668,7 @@
667	669	* Make UPDATE options for the Database::update function
668	670	*
669	671	* @private
670		~~- * @param array $options The options passed to Database::update~~
	672	+ * @param $options Array: The options passed to Database::update
671	673	* @return string
672	674	*/
673	675	function makeUpdateOptions( $options ) {
—	—	@@ -698,7 +700,7 @@
699	701
700	702	/**
701	703	* MSSQL doubles quotes instead of escaping them
702		~~- * @param string $s String to be slashed.~~
	704	+ * @param $s String to be slashed.
703	705	* @return string slashed string.
704	706	*/
705	707	function strencode($s) {
—	—	@@ -755,11 +757,12 @@
756	758	*
757	759	* DO NOT put the join condition in $conds
758	760	*
759		~~- * @param string $delTable The table to delete from.~~
760		~~- * @param string $joinTable The other table.~~
761		~~- * @param string $delVar The variable to join on, in the first table.~~
762		~~- * @param string $joinVar The variable to join on, in the second table.~~
763		~~- * @param array $conds Condition array of field names mapped to variables, ANDed together in the WHERE clause~~
	761	+ * @param $delTable String: The table to delete from.
	762	+ * @param $joinTable String: The other table.
	763	+ * @param $delVar String: The variable to join on, in the first table.
	764	+ * @param $joinVar String: The variable to join on, in the second table.
	765	+ * @param $conds Array: Condition array of field names mapped to variables, ANDed together in the WHERE clause
	766	+ * @param $fname String: Calling function name
764	767	*/
765	768	function deleteJoin( $delTable, $joinTable, $delVar, $joinVar, $conds, $fname = 'Database::deleteJoin' ) {
766	769	if ( !$conds ) {
—	—	@@ -857,9 +860,9 @@
858	861	/**
859	862	* Returns an SQL expression for a simple conditional.
860	863	*
861		~~- * @param string $cond SQL expression which will result in a boolean value~~
862		~~- * @param string $trueVal SQL expression to return if true~~
863		~~- * @param string $falseVal SQL expression to return if false~~
	864	+ * @param $cond String: SQL expression which will result in a boolean value
	865	+ * @param $trueVal String: SQL expression to return if true
	866	+ * @param $falseVal String: SQL expression to return if false
864	867	* @return string SQL fragment
865	868	*/
866	869	function conditional( $cond, $trueVal, $falseVal ) {
Index: trunk/phase3/includes/User.php
—	—	@@ -436,8 +436,7 @@
437	437	/**
438	438	* Get database id given a user name
439	439	* @param $name \string Username
440		~~- * @return \2types{\int,\null} The corresponding user's ID, or null if user is nonexistent~~
441		~~- * @static~~
	440	+ * @return \types{\int,\null} The corresponding user's ID, or null if user is nonexistent
442	441	*/
443	442	static function idFromName( $name ) {
444	443	$nt = Title::makeTitleSafe( NS_USER, $name );
—	—	@@ -631,7 +630,7 @@
632	631	* Given unvalidated user input, return a canonical username, or false if
633	632	* the username is invalid.
634	633	* @param $name \string User input
635		~~- * @param $validate \2types{\string,\bool} Type of validation to use:~~
	634	+ * @param $validate \types{\string,\bool} Type of validation to use:
636	635	* - false No validation
637	636	* - 'valid' Valid for batch processes
638	637	* - 'usable' Valid for batch processes and login
—	—	@@ -1487,7 +1486,7 @@
1488	1487	*
1489	1488	* @see getNewtalk()
1490	1489	* @param $field \string 'user_ip' for anonymous users, 'user_id' otherwise
1491		~~- * @param $id \2types{\string,\int} User's IP address for anonymous users, User ID otherwise~~
	1490	+ * @param $id \types{\string,\int} User's IP address for anonymous users, User ID otherwise
1492	1491	* @param $fromMaster \bool true to fetch from the master, false for a slave
1493	1492	* @return \bool True if the user has new messages
1494	1493	* @private
—	—	@@ -1506,7 +1505,7 @@
1507	1506	/**
1508	1507	* Add or update the new messages flag
1509	1508	* @param $field \string 'user_ip' for anonymous users, 'user_id' otherwise
1510		~~- * @param $id \2types{\string,\int} User's IP address for anonymous users, User ID otherwise~~
	1509	+ * @param $id \types{\string,\int} User's IP address for anonymous users, User ID otherwise
1511	1510	* @return \bool True if successful, false otherwise
1512	1511	* @private
1513	1512	*/
—	—	@@ -1528,7 +1527,7 @@
1529	1528	/**
1530	1529	* Clear the new messages flag for the given user
1531	1530	* @param $field \string 'user_ip' for anonymous users, 'user_id' otherwise
1532		~~- * @param $id \2types{\string,\int} User's IP address for anonymous users, User ID otherwise~~
	1531	+ * @param $id \types{\string,\int} User's IP address for anonymous users, User ID otherwise
1533	1532	* @return \bool True if successful, false otherwise
1534	1533	* @private
1535	1534	*/
—	—	@@ -2712,7 +2711,7 @@
2713	2712	* login credentials aren't being hijacked with a foreign form
2714	2713	* submission.
2715	2714	*
2716		~~- * @param $salt \2types{\string,\arrayof{\string}} Optional function-specific data for hashing~~
	2715	+ * @param $salt \types{\string,\arrayof{\string}} Optional function-specific data for hashing
2717	2716	* @return \string The new edit token
2718	2717	*/
2719	2718	function editToken( $salt = '' ) {
—	—	@@ -2778,7 +2777,7 @@
2779	2778	* Generate a new e-mail confirmation token and send a confirmation/invalidation
2780	2779	* mail to the user's given address.
2781	2780	*
2782		~~- * @return \2types{\bool,\type{WikiError}} True on success, a WikiError object on failure.~~
	2781	+ * @return \types{\bool,\type{WikiError}} True on success, a WikiError object on failure.
2783	2782	*/
2784	2783	function sendConfirmationMail() {
2785	2784	global $wgLang;
—	—	@@ -2805,7 +2804,7 @@
2806	2805	* @param $body \string Message body
2807	2806	* @param $from \string Optional From address; if unspecified, default $wgPasswordSender will be used
2808	2807	* @param $replyto \string Reply-To address
2809		~~- * @return \2types{\bool,\type{WikiError}} True on success, a WikiError object on failure~~
	2808	+ * @return \types{\bool,\type{WikiError}} True on success, a WikiError object on failure
2810	2809	*/
2811	2810	function sendMail( $subject, $body, $from = null, $replyto = null ) {
2812	2811	if( is_null( $from ) ) {
—	—	@@ -2983,7 +2982,7 @@
2984	2983	/**
2985	2984	* Get the timestamp of account creation.
2986	2985	*
2987		~~- * @return \2types{\string,\bool} string Timestamp of account creation, or false for~~
	2986	+ * @return \types{\string,\bool} string Timestamp of account creation, or false for
2988	2987	* non-existent/anonymous user accounts.
2989	2988	*/
2990	2989	public function getRegistration() {
—	—	@@ -3106,7 +3105,7 @@
3107	3106	* Get the title of a page describing a particular group
3108	3107	*
3109	3108	* @param $group \string Internal group name
3110		~~- * @return \2types{\type{Title},\bool} Title of the page if it exists, false otherwise~~
	3109	+ * @return \types{\type{Title},\bool} Title of the page if it exists, false otherwise
3111	3110	*/
3112	3111	static function getGroupPage( $group ) {
3113	3112	global $wgMessageCache;

Status & tagging log

19:18, 29 November 2008 Aaron Schulz (talk | contribs) changed the status of r44044 [removed: new added: ok]