Fix doxygen docs before REL1_19 branching

includes/CategoryViewer.php

@@ -12,7 +12,7 @@ class CategoryViewer extends ContextSource {
 		$imgsNoGallery;
 
 	/**
-	 * @var
+	 * @var Array
 	 */
 	var $nextPage;
 

includes/ChangesList.php

@@ -344,9 +344,11 @@ class ChangesList extends ContextSource {
 			$this->getLanguage()->time( $rc->mAttribs['rc_timestamp'], true, true ) . ' . . ';
 	}
 
-	/** Insert links to user page, user talk page and eventually a blocking link
+	/**
+	 * Insert links to user page, user talk page and eventually a blocking link
 	 *
-	 * @param $rc RecentChange
+	 * @param &$s String HTML to update
+	 * @param &$rc RecentChange
 	 */
 	public function insertUserRelatedLinks( &$s, &$rc ) {
 		if( $this->isDeleted( $rc, Revision::DELETED_USER ) ) {
@@ -359,7 +361,7 @@ class ChangesList extends ContextSource {
 	}
 
 	/**
-	 * insert a formatted action
+	 * Insert a formatted action
 	 *
 	 * @param $rc RecentChange
 	 */

includes/Html.php

@@ -376,20 +376,22 @@ class Html {
 	 * and converted to a space-separated string. In addition to a numerical
 	 * array, the attribute value may also be an associative array. See the
 	 * example below for how that works.
-	 * @example Numerical array
-	 * <code>
+	 *
+	 * @par Numerical array
+	 * @code
 	 *     Html::element( 'em', array(
 	 *         'class' => array( 'foo', 'bar' )
 	 *     ) );
 	 *     // gives '<em class="foo bar"></em>'
-	 * </code>
-	 * @example Associative array
-	 * <code>
+	 * @endcode
+	 *
+	 * @par Associative array
+	 * @code
 	 *     Html::element( 'em', array(
 	 *         'class' => array( 'foo', 'bar', 'foo' => false, 'quux' => true )
 	 *     ) );
 	 *     // gives '<em class="bar quux"></em>'
-	 * </code>
+	 * @endcode
 	 *
 	 * @param $attribs array Associative array of attributes, e.g., array(
 	 *   'href' => 'http://www.mediawiki.org/' ).  Values will be HTML-escaped.

includes/Linker.php

@@ -241,6 +241,8 @@ class Linker {
 	 * Returns the Url used to link to a Title
 	 *
 	 * @param $target Title
+	 * @param $query Array: query parameters
+	 * @param $options Array
 	 */
 	private static function linkUrl( $target, $query, $options ) {
 		wfProfileIn( __METHOD__ );

includes/MagicWord.php

@@ -10,8 +10,13 @@
 
 /**
  * This class encapsulates "magic words" such as #redirect, __NOTOC__, etc.
- * Usage:
- *     if (MagicWord::get( 'redirect' )->match( $text ) )
+ *
+ * @par Usage:
+ * @code
+ *     if (MagicWord::get( 'redirect' )->match( $text ) ) {
+ *       // some code
+ *     }
+ * @endcode
  *
  * Possible future improvements:
  *   * Simultaneous searching for a number of magic words
@@ -23,14 +28,15 @@
  * To add magic words in an extension, use $magicWords in a file listed in
  * $wgExtensionMessagesFiles[].
  * 
- * Example:
- *
+ * @par Example:
+ * @code
  * $magicWords = array();
  *
  * $magicWords['en'] = array(
  * 	'magicwordkey' => array( 0, 'case_insensitive_magic_word' ),
  * 	'magicwordkey2' => array( 1, 'CASE_sensitive_magic_word2' ),
  * );
+ * @endcode
  *
  * For magic words which are also Parser variables, add a MagicWordwgVariableIDs
  * hook. Use string keys.

includes/PHPVersionError.php

@@ -7,7 +7,7 @@
  *
  * Calling this function kills execution immediately.
  *
- * @param $entryPoint String Which entry point we're protecting. One of:
+ * @param $type String Which entry point we are protecting. One of:
  *   - index.php
  *   - load.php
  *   - api.php
@@ -88,4 +88,4 @@ HTML;
 	}
 	echo( "$finalOutput\n" );
 	die( 1 );
-}
+}

includes/UserMailer.php

@@ -109,8 +109,8 @@ class UserMailer {
 	/**
 	 * Creates a single string from an associative array
 	 *
-	 * @param $header Associative Array: keys are header field names,
-	 *                values are ... values.
+	 * @param $headers Associative Array: keys are header field names,
+	 *                 values are ... values.
 	 * @param $endl String: The end of line character.  Defaults to "\n"
 	 * @return String
 	 */

includes/WebResponse.php

@@ -131,9 +131,14 @@ class FauxResponse extends WebResponse {
 	}
 
 	/**
+	 * @todo document. It just ignore optional parameters.
+	 *
 	 * @param $name String: name of cookie
 	 * @param $value String: value to give cookie
-	 * @param $expire Int: number of seconds til cookie expires
+	 * @param $expire Int: number of seconds til cookie expires (Default: 0)
+	 * @param $prefix TODO DOCUMENT (Default: null)
+	 * @param $domain TODO DOCUMENT (Default: null)
+	 *
 	 */
 	public function setcookie( $name, $value, $expire = 0, $prefix = null, $domain = null ) {
 		$this->cookies[$name] = $value;

includes/WikiPage.php

@@ -1900,7 +1900,7 @@ class WikiPage extends Page {
 	 * 	Revision::DELETED_RESTRICTED
 	 * @param $id int article ID
 	 * @param $commit boolean defaults to true, triggers transaction end
-	 * @param &$errors Array of errors to append to
+	 * @param &$error Array of errors to append to
 	 * @param $user User The relevant user
 	 * @return boolean true if successful
 	 */

includes/actions/CreditsAction.php

@@ -219,8 +219,7 @@ class CreditsAction extends FormlessAction {
 
 	/**
 	 * Get a link to action=credits of $article page
-	 * @param $article Article object
-	 * @return String: html
+	 * @return String: HTML link
 	 */
 	protected function othersLink() {
 		return Linker::linkKnown(

includes/actions/WatchAction.php

@@ -106,7 +106,7 @@ class WatchAction extends FormAction {
 	 * Get token to watch (or unwatch) a page for a user
 	 *
 	 * @param Title $title Title object of page to watch
-	 * @param User $title User for whom the action is going to be performed
+	 * @param User $user User for whom the action is going to be performed
 	 * @param string $action Optionally override the action to 'unwatch'
 	 * @return string Token
 	 * @since 1.18
@@ -126,7 +126,7 @@ class WatchAction extends FormAction {
 	 * Get token to unwatch (or watch) a page for a user
 	 *
 	 * @param Title $title Title object of page to unwatch
-	 * @param User $title User for whom the action is going to be performed
+	 * @param User $user User for whom the action is going to be performed
 	 * @param string $action Optionally override the action to 'watch'
 	 * @return string Token
 	 * @since 1.18

includes/conf/Conf.php

@@ -25,7 +25,6 @@
  *
  * @file
  * @defgroup Config Config
- * @ingroup Config
  */
 abstract class Conf {
 	/**

includes/db/Database.php

@@ -1432,7 +1432,7 @@ abstract class DatabaseBase implements DatabaseType {
 	 *
 	 * @param $table string|array Table name
 	 * @param $vars string|array Field names
-	 * @param $conds|array Conditions
+	 * @param $conds array Conditions
 	 * @param $fname string Caller function name
 	 * @param $options string|array Query options
 	 * @param $join_conds array|string Join conditions

includes/db/DatabaseIbm_db2.php

@@ -893,7 +893,7 @@ class DatabaseIbm_db2 extends DatabaseBase {
 	 * Handle reserved keyword replacement in table names
 	 *
 	 * @param $name Object
-	 * @param $name Boolean
+	 * @param $format String Ignored parameter Default 'quoted'Boolean
 	 * @return String
 	 */
 	public function tableName( $name, $format = 'quoted' ) {

includes/filerepo/LocalRepo.php

@@ -208,10 +208,10 @@ class LocalRepo extends FileRepo {
 	}
 
 	/**
-	 * Get an array or iterator of file objects for files that have a given 
+	 * Get an array or iterator of file objects for files that have a given
 	 * SHA-1 content hash.
 	 *
-	 * @param string
+	 * @param $hash String a sha1 hash to look for
 	 * @return Array
 	 */
 	function findBySha1( $hash ) {

includes/installer/PhpBugTests.php

@@ -18,8 +18,7 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @defgroup PHPBugTests
- * @ingroup PHPBugTests
+ * @defgroup PHPBugTests PHP known bugs tests
  */
 
 /**

includes/logging/LogEventsList.php

@@ -230,7 +230,6 @@ class LogEventsList {
 
 	/**
 	 * Returns log page selector.
-	 * @param $default string The default selection
 	 * @return XmlSelect
 	 * @since 1.19
 	 */

includes/media/BitmapMetadataHandler.php

@@ -52,7 +52,10 @@ class BitmapMetadataHandler {
 	 * Basically what used to be in BitmapHandler::getMetadata().
 	 * Just calls stuff in the Exif class.
 	 *
+	 * Parameters are passed to the Exif class.
+	 *
 	 * @param $filename string
+	 * @param $byteOrder string
 	 */
 	function getExif ( $filename, $byteOrder ) {
 		global $wgShowEXIF;

includes/media/DjVu.php

@@ -190,6 +190,7 @@ class DjVuHandler extends ImageHandler {
 	/**
 	 * Cache a document tree for the DjVu XML metadata
 	 * @param $image File
+	 * @param $gettext Boolean: DOCUMENT (Default: false)
 	 */
 	function getMetaTree( $image , $gettext = false ) {
 		if ( isset( $image->dejaMetaTree ) ) {

includes/media/Exif.php

@@ -101,6 +101,7 @@ class Exif {
 	 * Constructor
 	 *
 	 * @param $file String: filename.
+	 * @param $byteOrder String Type of byte ordering either 'BE' (Big Endian) or 'LE' (Little Endian). Default ''.
 	 * @todo FIXME: The following are broke:
 	 * SubjectArea. Need to test the more obscure tags.
 	 *

includes/media/FormatMetadata.php

@@ -1183,7 +1183,7 @@ class FormatMetadata {
 	 * Format a coordinate value, convert numbers from floating point
 	 * into degree minute second representation.
 	 *
-	 * @param $coords Array: degrees, minutes and seconds
+	 * @param $coord Array: degrees, minutes and seconds
 	 * @param $type String: latitude or longitude (for if its a NWS or E)
 	 * @return mixed A floating point number or whatever we were fed
 	 */

includes/media/Generic.php

@@ -364,7 +364,7 @@ abstract class MediaHandler {
 	 * @param &$array Array An array containing elements for each type of visibility
 	 * and each of those elements being an array of metadata items. This function adds
 	 * a value to that array.
-	 * @param $visbility string ('visible' or 'collapsed') if this value is hidden
+	 * @param $visibility string ('visible' or 'collapsed') if this value is hidden
 	 * by default.
 	 * @param $type String type of metadata tag (currently always 'exif')
 	 * @param $id String the name of the metadata tag (like 'artist' for example).

includes/media/XMP.php

@@ -210,9 +210,9 @@ class XMPReader {
 	* Also catches any errors during processing, writes them to
 	* debug log, blanks result array and returns false.
 	*
-	* @param String: $content XMP data
-	* @param Boolean: $allOfIt If this is all the data (true) or if its split up (false). Default true
-	* @param Boolean: $reset - does xml parser need to be reset. Default false
+	* @param $content String: XMP data
+	* @param $allOfIt Boolean: If this is all the data (true) or if its split up (false). Default true
+	* @param $reset Boolean: does xml parser need to be reset. Default false
 	* @return Boolean success.
 	*/
 	public function parse( $content, $allOfIt = true, $reset = false ) {

includes/parser/CoreParserFunctions.php

@@ -562,7 +562,11 @@ class CoreParserFunctions {
 	 *   to the link cache, so the local cache here should be unnecessary, but
 	 *   in fact calling getLength() repeatedly for the same $page does seem to
 	 *   run one query for each call?
+	 * @todo Document parameters
+	 *
 	 * @param $parser Parser
+	 * @param $page String TODO DOCUMENT (Default: empty string)
+	 * @param $raw TODO DOCUMENT (Default: null)
 	 */
 	static function pagesize( $parser, $page = '', $raw = null ) {
 		static $cache = array();

includes/parser/ParserCache.php

@@ -100,6 +100,8 @@ class ParserCache {
 	 * It would be preferable to have this code in get()
 	 * instead of having Article looking in our internals.
 	 *
+	 * @todo Document parameter $useOutdated
+	 *
 	 * @param $article Article
 	 * @param $popts ParserOptions
 	 */

includes/parser/ParserOutput.php

@@ -285,7 +285,7 @@ class ParserOutput extends CacheTime {
 	 * Register a file dependency for this output
 	 * @param $name string Title dbKey
 	 * @param $timestamp string MW timestamp of file creation (or false if non-existing)
-	 * @param $sha string base 36 SHA-1 of file (or false if non-existing)
+	 * @param $sha1 string base 36 SHA-1 of file (or false if non-existing)
 	 * @return void
 	 */
 	function addImage( $name, $timestamp = null, $sha1 = null ) {

includes/search/SearchMySQL.php

@@ -45,7 +45,7 @@ class SearchMySQL extends SearchEngine {
 	 * become part of a WHERE clause
 	 *
 	 * @param $filteredText string
-	 * @param $fullText string
+	 * @param $fulltext string
 	 *
 	 * @return string
 	 */
@@ -290,6 +290,7 @@ class SearchMySQL extends SearchEngine {
 	/**
 	 * Get the base part of the search query.
 	 *
+	 * @param &$query Search query array
 	 * @param $filteredTerm String
 	 * @param $fulltext Boolean
 	 * @since 1.18 (changed)

includes/specials/SpecialListusers.php

@@ -263,6 +263,7 @@ class UsersPager extends AlphabeticPager {
 	 * Format a link to a group description page
 	 *
 	 * @param $group String: group name
+	 * @param $username String Username
 	 * @return string
 	 */
 	protected static function buildGroupLink( $group, $username ) {

includes/specials/SpecialUndelete.php

@@ -1263,6 +1263,8 @@ class SpecialUndelete extends SpecialPage {
 	 * Fetch revision text link if it's available to all users
 	 *
 	 * @param $rev Revision
+	 * @param $titleObj Title
+	 * @param $ts Timestamp
 	 * @return string
 	 */
 	function getPageLink( $rev, $titleObj, $ts ) {
@@ -1292,6 +1294,10 @@ class SpecialUndelete extends SpecialPage {
 	 * Fetch image view link if it's available to all users
 	 *
 	 * @param $file File
+	 * @param $titleObj Title
+	 * @param $ts A timestamp
+	 * @param $key String: a storage key
+	 *
 	 * @return String: HTML fragment
 	 */
 	function getFileLink( $file, $titleObj, $ts, $key ) {

includes/specials/SpecialUserlogin.php

@@ -72,8 +72,6 @@ class LoginForm extends SpecialPage {
 
 	/**
 	 * Loader
-	 *
-	 * @param $request WebRequest object
 	 */
 	function load() {
 		global $wgAuth, $wgHiddenPrefs, $wgEnableEmail, $wgRedirectOnLogin;

includes/specials/SpecialUserrights.php

@@ -493,7 +493,9 @@ class UserrightsPage extends SpecialPage {
 	/**
 	 * Adds a table with checkboxes where you can select what groups to add/remove
 	 *
+	 * @todo Just pass the username string?
 	 * @param $usergroups Array: groups the user belongs to
+	 * @param $user User a user object
 	 * @return string XHTML table element with checkboxes
 	 */
 	private function groupCheckboxes( $usergroups, $user ) {

languages/Language.php

@@ -1261,7 +1261,7 @@ class Language {
 	 *
 	 * Based on a PHP-Nuke block by Sharjeel which is released under GNU/GPL license
 	 *
-	 * @link http://phpnuke.org/modules.php?name=News&file=article&sid=8234&mode=thread&order=0&thold=0
+	 * @see http://phpnuke.org/modules.php?name=News&file=article&sid=8234&mode=thread&order=0&thold=0
 	 *
 	 * @param $ts string
 	 *

languages/classes/LanguageBe.php

@@ -7,7 +7,7 @@
   * @ingroup Language
   *
   * @author Ævar Arnfjörð Bjarmason <avarab@gmail.com>
-  * @link http://be.wikipedia.org/wiki/Talk:LanguageBe.php
+  * @see http://be.wikipedia.org/wiki/Talk:LanguageBe.php
   * @license http://www.gnu.org/copyleft/gpl.html GNU General Public License
   * @license http://www.gnu.org/copyleft/fdl.html GNU Free Documentation License
   */

languages/classes/LanguageBe_tarask.php

@@ -4,7 +4,7 @@
   * @ingroup Language
   *
   * @author Ævar Arnfjörð Bjarmason <avarab@gmail.com>
-  * @link http://be-x-old.wikipedia.org/wiki/Project_talk:LanguageBe_tarask.php
+  * @see http://be-x-old.wikipedia.org/wiki/Project_talk:LanguageBe_tarask.php
   * @license http://www.gnu.org/copyleft/gpl.html GNU General Public License
   * @license http://www.gnu.org/copyleft/fdl.html GNU Free Documentation License
   */

maintenance/nextJobDB.php

@@ -106,7 +106,6 @@ class nextJobDB extends Maintenance {
 
 	/**
 	 * Get all databases that have a pending job
-	 * @param $type String Job type
 	 * @return array
 	 */
 	private function getPendingDbs() {

maintenance/parse.php

@@ -88,7 +88,7 @@ class CLIParser extends Maintenance {
 	}
 
 	/**
-	 * @param string $text Wikitext to parse
+	 * @param string $wikitext Wikitext to parse
 	 * @return ParserOutput
 	 */
 	protected function parse( $wikitext ) {

tests/phpunit/includes/TitleTest.php

@@ -44,7 +44,7 @@ class TitleTest extends MediaWikiTestCase {
 	 * @group Database
 	 * @param string $source
 	 * @param string $target
-	 * @param array|string|true $requiredErrors
+	 * @param array|string|true $expected Required error
 	 * @dataProvider dataTestIsValidMoveOperation
 	 */
 	function testIsValidMoveOperation( $source, $target, $expected ) {

tests/phpunit/includes/api/ApiTestCase.php

@@ -70,6 +70,7 @@ abstract class ApiTestCase extends MediaWikiLangTestCase {
 	 * request, without actually requesting a "real" edit token
 	 * @param $params: key-value API params
 	 * @param $session: session array
+	 * @param $user String|null A User object for the context 
 	 */
 	protected function doApiRequestWithToken( $params, $session, $user = null ) {
 		if ( $session['wsToken'] ) {

tests/phpunit/includes/specials/SpecialSearchTest.php

@@ -18,10 +18,12 @@ class SpecialSearchTest extends MediaWikiTestCase {
 	 * @dataProvider provideSearchOptionsTests
 	 * @param $requested Array Request parameters. For example array( 'ns5' => true, 'ns6' => true). NULL to use default options.
 	 * @param $userOptions Array User options to test with. For example array('searchNs5' => 1 );. NULL to use default options.
+	 * @param $expectedProfile An expected search profile name
+	 * @param $expectedNs Array Expected namespaces
 	 */
 	function testProfileAndNamespaceLoading(
 		$requested, $userOptions, $expectedProfile, $expectedNS,
-		$message = 'Profile name andnamespaces mismatches!'
+		$message = 'Profile name and namespaces mismatches!'
 	) {
 		$context = new RequestContext;
 		$context->setUser(

tests/phpunit/languages/LanguageTrTest.php

@@ -18,7 +18,10 @@ class LanguageTrTest extends MediaWikiTestCase {
 
 	/**
 	 * See @bug 28040
-	 * Credits to #wikipedia-tr users berm, []LuCkY[] and Emperyan
+	 * Credits to irc://irc.freenode.net/wikipedia-tr users:
+	 *  - berm
+	 *  - []LuCkY[]
+	 *  - Emperyan
 	 * @see http://en.wikipedia.org/wiki/Dotted_and_dotless_I
 	 * @dataProvider provideDottedAndDotlessI
 	 */