Add missing @return and @param to doc blocks

Change-Id: I9d99ba1968ed8f97624d957754c8847dfe1b41da

includes/Setup.php

@@ -596,7 +596,7 @@ if ( !is_object( $wgAuth ) ) {
 $wgTitle = null;
 
 /**
- * @deprecated 1.24 Use DeferredUpdates::addUpdate instead
+ * @deprecated since 1.24 Use DeferredUpdates::addUpdate instead
  * @var array
  */
 $wgDeferredUpdateList = array();

includes/content/MessageContent.php

@@ -106,7 +106,7 @@ class MessageContent extends AbstractContent {
 	}
 
 	/**
-	 * @param int $maxLength Maximum length of the summary text, defaults to 250.
+	 * @param int $maxlength Maximum length of the summary text, defaults to 250.
 	 *
 	 * @return string The summary text.
 	 *

includes/context/RequestContext.php

@@ -425,6 +425,7 @@ class RequestContext implements IContextSource {
 	 * Get the RequestContext object associated with the main request
 	 * and gives a warning to the log, to find places, where a context maybe is missing.
 	 *
+	 * @param string $func
 	 * @return RequestContext
 	 * @since 1.24
 	 */

includes/resourceloader/ResourceLoaderLESSFunctions.php

@@ -34,6 +34,8 @@ class ResourceLoaderLESSFunctions {
 	 *       background-image: url(@url) !ie;
 	 *   }
 	 * @endcode
+	 * @param array $frame
+	 * @param lessc $less
 	 */
 	public static function embeddable( $frame, $less ) {
 		$base = pathinfo( $less->parser->sourceName, PATHINFO_DIRNAME );
@@ -54,6 +56,9 @@ class ResourceLoaderLESSFunctions {
 	 *       background-image: embed('../images/button-bg.png');
 	 *   }
 	 * @endcode
+	 * @param array $frame
+	 * @param lessc $less
+	 * @return string
 	 */
 	public static function embed( $frame, $less ) {
 		$base = pathinfo( $less->parser->sourceName, PATHINFO_DIRNAME );

includes/search/SearchHighlighter.php

@@ -560,8 +560,8 @@ class SearchHighlighter {
 	 * Returns the first few lines of the text
 	 *
 	 * @param string $text
-	 * @param int $contextlines max number of returned lines
-	 * @param int $contextchars average number of characters per line
+	 * @param int $contextlines Max number of returned lines
+	 * @param int $contextchars Average number of characters per line
 	 * @return string
 	 */
 	public function highlightNone( $text, $contextlines, $contextchars ) {

languages/LanguageConverter.php

@@ -1102,6 +1102,7 @@ class LanguageConverter {
 
 	/**
 	 * Get the cached separator pattern for ConverterRule::parseRules()
+	 * @return string
 	 */
 	function getVarSeparatorPattern() {
 		if ( is_null( $this->mVarSeparatorPattern ) ) {

maintenance/preprocessorFuzzTest.php

@@ -159,6 +159,7 @@ class PPFuzzTest {
 
 	/**
 	 * @param Title $title
+	 * @return array
 	 */
 	function templateHook( $title ) {
 		$titleText = $title->getPrefixedDBkey();

maintenance/updateCollation.php

@@ -221,6 +221,7 @@ TEXT;
 	 * assuming an ordering of cl_to, cl_type, cl_from
 	 * @param stdClass $row
 	 * @param DatabaseBase $dbw
+	 * @return string
 	 */
 	function getBatchCondition( $row, $dbw ) {
 		$fields = array( 'cl_to', 'cl_type', 'cl_from' );

tests/parser/parserTest.inc

@@ -332,6 +332,7 @@ class ParserTest {
 	 * Remove last character if it is a newline
 	 * @group utility
 	 * @param string $s
+	 * @return string
 	 */
 	public static function chomp( $s ) {
 		if ( substr( $s, -1 ) === "\n" ) {
@@ -416,6 +417,7 @@ class ParserTest {
 	/**
 	 * Get an input dictionary from a set of parser test files
 	 * @param array $filenames
+	 * @return string
 	 */
 	function getFuzzInput( $filenames ) {
 		$dict = '';
@@ -438,6 +440,7 @@ class ParserTest {
 
 	/**
 	 * Get a memory usage breakdown
+	 * @return array
 	 */
 	function getMemoryBreakdown() {
 		$memStats = array();
@@ -663,6 +666,7 @@ class ParserTest {
 	/**
 	 * Refactored in 1.22 to use ParserTestResult
 	 * @param ParserTestResult $testResult
+	 * @return bool
 	 */
 	function showTestResult( ParserTestResult $testResult ) {
 		if ( $testResult->isSuccess() ) {
@@ -679,6 +683,7 @@ class ParserTest {
 	 * @param string $key Name of option val to retrieve
 	 * @param array $opts Options array to look in
 	 * @param mixed $default Default value returned if not found
+	 * @return mixed
 	 */
 	private static function getOptionValue( $key, $opts, $default ) {
 		$key = strtolower( $key );
@@ -782,6 +787,7 @@ class ParserTest {
 	 * Ideally this should replace the global configuration entirely.
 	 * @param string $opts
 	 * @param string $config
+	 * @return RequestContext
 	 */
 	private function setupGlobals( $opts = '', $config = '' ) {
 		global $IP;
@@ -929,6 +935,7 @@ class ParserTest {
 	/**
 	 * List of temporary tables to create, without prefix.
 	 * Some of these probably aren't necessary.
+	 * @return array
 	 */
 	private function listTables() {
 		$tables = array( 'user', 'user_properties', 'user_former_groups', 'page', 'page_restrictions',

tests/phpunit/includes/EditPageTest.php

@@ -59,6 +59,9 @@ class EditPageTest extends MediaWikiLangTestCase {
 	 * User input text is passed to rtrim() by edit page. This is a simple
 	 * wrapper around assertEquals() which calls rrtrim() to normalize the
 	 * expected and actual texts.
+	 * @param string $expected
+	 * @param string $actual
+	 * @param string $msg
 	 */
 	protected function assertEditedTextEquals( $expected, $actual, $msg = '' ) {
 		return $this->assertEquals( rtrim( $expected ), rtrim( $actual ), $msg );

tests/phpunit/includes/parser/NewParserTest.php

@@ -353,6 +353,9 @@ class NewParserTest extends MediaWikiTestCase {
 	/**
 	 * Set up the global variables for a consistent environment for each test.
 	 * Ideally this should replace the global configuration entirely.
+	 * @param array $opts
+	 * @param string $config
+	 * @return RequestContext
 	 */
 	protected function setupGlobals( $opts = array(), $config = '' ) {
 		global $wgFileBackends;
@@ -872,6 +875,7 @@ class NewParserTest extends MediaWikiTestCase {
 	/**
 	 * Get an input dictionary from a set of parser test files
 	 * @param array $filenames
+	 * @return string
 	 */
 	function getFuzzInput( $filenames ) {
 		$dict = '';
@@ -890,6 +894,7 @@ class NewParserTest extends MediaWikiTestCase {
 
 	/**
 	 * Get a memory usage breakdown
+	 * @return array
 	 */
 	function getMemoryBreakdown() {
 		$memStats = array();
@@ -926,6 +931,7 @@ class NewParserTest extends MediaWikiTestCase {
 	/**
 	 * Get a Parser object
 	 * @param Preprocessor $preprocessor
+	 * @return Parser
 	 */
 	function getParser( $preprocessor = null ) {
 		global $wgParserConf;
@@ -986,6 +992,7 @@ class NewParserTest extends MediaWikiTestCase {
 	/**
 	 * Remove last character if it is a newline
 	 * @param string $s
+	 * @return string
 	 */
 	public function removeEndingNewline( $s ) {
 		if ( substr( $s, -1 ) === "\n" ) {
@@ -1070,6 +1077,7 @@ class NewParserTest extends MediaWikiTestCase {
 	 * @param string $key Name of option val to retrieve
 	 * @param array $opts Options array to look in
 	 * @param mixed $default Default value returned if not found
+	 * @return mixed
 	 */
 	protected static function getOptionValue( $key, $opts, $default ) {
 		$key = strtolower( $key );

tests/phpunit/includes/upload/UploadFromUrlTest.php

@@ -270,6 +270,9 @@ class UploadFromUrlTest extends ApiTestCase {
 	 * Helper function to perform an async upload, execute the job and fetch
 	 * the status
 	 *
+	 * @param string $token
+	 * @param bool $ignoreWarnings
+	 * @param bool $leaveMessage
 	 * @return array The result of action=upload&statuskey=key
 	 */
 	private function doAsyncUpload( $token, $ignoreWarnings = false, $leaveMessage = false ) {

tests/phpunit/includes/utils/StringUtilsTest.php

@@ -35,7 +35,9 @@ class StringUtilsTest extends MediaWikiTestCase {
 	}
 
 	/**
-	 * Print high range characters as an hexadecimal
+	 * Print high range characters as a hexadecimal
+	 * @param string $string
+	 * @return string
 	 */
 	function escaped( $string ) {
 		$escaped = '';

tests/phpunit/maintenance/DumpTestCase.php

@@ -31,7 +31,7 @@ abstract class DumpTestCase extends MediaWikiLangTestCase {
 	 * @param Page $page Page to add the revision to
 	 * @param string $text Revisions text
 	 * @param string $summary Revisions summare
-	 *
+	 * @return array
 	 * @throws MWException
 	 */
 	protected function addRevision( Page $page, $text, $summary ) {

tests/phpunit/maintenance/fetchTextTest.php

@@ -101,7 +101,7 @@ class FetchTextTest extends MediaWikiTestCase {
 	 * @param WikiPage $page The page to add the revision to
 	 * @param string $text The revisions text
 	 * @param string $summary The revisions summare
-	 *
+	 * @return int
 	 * @throws MWException
 	 */
 	private function addRevision( $page, $text, $summary ) {

tests/phpunit/structure/ResourcesTest.php

@@ -106,6 +106,7 @@ class ResourcesTest extends MediaWikiTestCase {
 
 	/**
 	 * Get all registered modules from ResouceLoader.
+	 * @return array
 	 */
 	protected static function getAllModules() {
 		global $wgEnableJavaScriptTest;

tests/phpunit/structure/StructureTest.php

@@ -58,6 +58,8 @@ class StructureTest extends MediaWikiTestCase {
 
 	/**
 	 * Filter to remove testUnitTestFileNamesEndWithTest false positives.
+	 * @param string $filename
+	 * @return bool
 	 */
 	public function filterSuites( $filename ) {
 		return strpos( $filename, __DIR__ . '/../suites/' ) !== 0;

tests/phpunit/suites/UploadFromUrlTestSuite.php

@@ -95,6 +95,7 @@ class UploadFromUrlTestSuite extends PHPUnit_Framework_TestSuite {
 
 	/**
 	 * Remove the dummy uploads directory
+	 * @param string $dir
 	 */
 	private function teardownUploadDir( $dir ) {
 		if ( $this->keepUploads ) {

tests/testHelpers.inc

@@ -36,16 +36,26 @@
  */
 interface ITestRecorder {
 
-	/** Called at beginning of the parser test run */
+	/**
+	 * Called at beginning of the parser test run
+	 */
 	public function start();
 
-	/** Called after each test */
+	/**
+	 * Called after each test
+	 * @param string $test
+	 * @param bool $result
+	 */
 	public function record( $test, $result );
 
-	/** Called before finishing the test run */
+	/**
+	 * Called before finishing the test run
+	 */
 	public function report();
 
-	/** Called at the end of the parser test run */
+	/**
+	 * Called at the end of the parser test run
+	 */
 	public function end();
 
 }
@@ -107,6 +117,7 @@ class DbTestPreviewer extends TestRecorder {
 
 	/**
 	 * This should be called before the table prefix is changed
+	 * @param TestRecorder $parent
 	 */
 	function __construct( $parent ) {
 		parent::__construct( $parent );
@@ -220,6 +231,9 @@ class DbTestPreviewer extends TestRecorder {
 	 * Returns a string giving information about when a test last had a status change.
 	 * Could help to track down when regressions were introduced, as distinct from tests
 	 * which have never passed (which are more change requests than regressions).
+	 * @param string $testname
+	 * @param string $after
+	 * @return string
 	 */
 	private function getTestStatusInfo( $testname, $after ) {
 		// If we're looking at a test that has just been removed, then say when it first appeared.
@@ -603,6 +617,7 @@ class TestFileIterator implements Iterator {
 	 * mentioned before closing this section
 	 * @param bool $fatal True iff an exception should be thrown if
 	 * the section is not found.
+	 * @return bool|string
 	 */
 	private function checkSection( $tokens, $fatal = true ) {
 		if ( is_null( $this->section ) ) {
@@ -675,6 +690,7 @@ class DelayedParserTest {
 	 * Called whenever we actually want to run the hook.
 	 * Should be the case if we found the parserTest is not disabled
 	 * @param ParserTest|NewParserTest $parserTest
+	 * @return bool
 	 */
 	public function unleash( &$parserTest ) {
 		if ( !( $parserTest instanceof ParserTest || $parserTest instanceof NewParserTest )	) {