Improve some parameter docs

Change-Id: If7d52d77935b7dd6cddd583b9a6215735fa8b91e

Math.hooks.php

@@ -100,12 +100,13 @@ class MathHooks {
 		}
 	}
 
-	/*
+	/**
 	 * Generate a user dependent hash cache key.
 	 * The hash key depends on the rendering mode.
-	 * @param &$confstr The to-be-hashed key string that is being constructed
+	 * @param string &$confstr The to-be-hashed key string that is being constructed
 	 * @param User $user reference to the current user
 	 * @param array &$forOptions userOptions used on that page
+	 * @return true
 	 */
 	public static function onPageRenderingHash( &$confstr, $user = false, &$forOptions = [] ) {
 		global $wgUser;
@@ -166,8 +167,8 @@ class MathHooks {
 	/**
 	 * Register the <math> tag with the Parser.
 	 *
-	 * @param $parser Parser instance of Parser
-	 * @return Boolean: true
+	 * @param Parser $parser instance of Parser
+	 * @return bool true
 	 */
 	static function onParserFirstCallInit( $parser ) {
 		$parser->setHook( 'math', [ 'MathHooks', 'mathTagHook' ] );
@@ -181,8 +182,8 @@ class MathHooks {
 	/**
 	 * Callback function for the <math> parser hook.
 	 *
-	 * @param $content (the LaTeX input)
-	 * @param $attributes
+	 * @param string $content (the LaTeX input)
+	 * @param array $attributes
 	 * @param Parser $parser
 	 * @return array
 	 */
@@ -253,9 +254,9 @@ class MathHooks {
 	/**
 	 * Add the new math rendering options to Special:Preferences.
 	 *
-	 * @param $user Object: current User object
-	 * @param $defaultPreferences Object: Preferences object
-	 * @return Boolean: true
+	 * @param User $user current User object
+	 * @param array &$defaultPreferences Preferences array
+	 * @return bool true
 	 */
 	static function onGetPreferences( $user, &$defaultPreferences ) {
 		global $wgDefaultUserOptions;
@@ -311,7 +312,7 @@ class MathHooks {
 	/**
 	 * LoadExtensionSchemaUpdates handler; set up math table on install/upgrade.
 	 *
-	 * @param $updater DatabaseUpdater
+	 * @param DatabaseUpdater $updater
 	 * @throws Exception
 	 * @return bool
 	 */
@@ -357,7 +358,7 @@ class MathHooks {
 	 * Add 'math' and 'mathlatexml' tables to the list of tables that need to be copied to
 	 * temporary tables for parser tests to run.
 	 *
-	 * @param array $tables
+	 * @param array &$tables
 	 * @return bool
 	 */
 	static function onParserTestTables( &$tables ) {
@@ -367,8 +368,8 @@ class MathHooks {
 	}
 
 	/**
-	 * @param Parser $parser
-	 * @param $text
+	 * @param Parser &$parser
+	 * @param string &$text
 	 * @return bool
 	 */
 	public static function onParserAfterTidy( &$parser, &$text ) {
@@ -395,7 +396,7 @@ class MathHooks {
 	}
 
 	/**
-	 * @param string $toolbar HTML
+	 * @param string &$toolbar HTML
 	 */
 	static function onEditPageBeforeEditToolbar( &$toolbar ) {
 		global $wgOut;
@@ -415,8 +416,8 @@ class MathHooks {
 	/**
 	 * Callback function for the <ce> parser hook.
 	 *
-	 * @param $content (the LaTeX input)
-	 * @param $attributes
+	 * @param string $content (the LaTeX input)
+	 * @param array $attributes
 	 * @param Parser $parser
 	 * @return array
 	 */

MathInputCheckRestbase.php

@@ -17,7 +17,7 @@ class MathInputCheckRestbase extends MathInputCheck {
 	 * (performs no checking)
 	 * @param string $tex the TeX input string to be checked
 	 * @param string $type
-	 * @param MathRestbaseInterface $ref
+	 * @param MathRestbaseInterface &$ref
 	 */
 	public function __construct( $tex = '', $type = 'tex', &$ref = null ) {
 		parent::__construct( $tex );

MathLaTeXML.php

@@ -151,8 +151,7 @@ class MathLaTeXML extends MathMathML {
 
 	/**
 	 * Internal version of @link self::embedMathML
-	 * @return string
-	 * @return html element with rendered math
+	 * @return string html element with rendered math
 	 */
 	protected function getMathMLTag() {
 		return self::embedMathML( $this->getMathml(), urldecode( $this->getTex() ) );

MathMathML.php

@@ -18,7 +18,7 @@ class MathMathML extends MathRenderer {
 	protected $allowedRootElements = '';
 	protected $hosts;
 
-	/** @var boolean if false MathML output is not validated */
+	/** @var bool if false MathML output is not validated */
 	private $XMLValidation = true;
 
 	/**
@@ -65,7 +65,7 @@ class MathMathML extends MathRenderer {
 	/**
 	 * Sets the XML validation.
 	 * If set to false the output of MathML is not validated.
-	 * @param boolean $validation
+	 * @param bool $validation
 	 */
 	public function setXMLValidation( $validation = true ) {
 		$this->XMLValidation = $validation;
@@ -80,9 +80,11 @@ class MathMathML extends MathRenderer {
 		$this->allowedRootElements = $settings;
 	}
 
-	/* (non-PHPdoc)
+	/**
 	 * @see MathRenderer::render()
-	*/
+	 * @param bool $forceReRendering
+	 * @return bool
+	 */
 	public function render( $forceReRendering = false ) {
 		global $wgMathFullRestbaseURL;
 		try {
@@ -122,7 +124,7 @@ class MathMathML extends MathRenderer {
 
 	/**
 	 * Helper function to checks if the math tag must be rendered.
-	 * @return boolean
+	 * @return bool
 	 */
 	private function renderingRequired() {
 		$logger = LoggerFactory::getInstance( 'Math' );
@@ -161,8 +163,8 @@ class MathMathML extends MathRenderer {
 	 * @global int $wgMathLaTeXMLTimeout
 	 * @param string $host
 	 * @param string $post the encoded post request
-	 * @param mixed $res the result
-	 * @param mixed $error the formatted error message or null
+	 * @param mixed &$res the result
+	 * @param mixed &$error the formatted error message or null
 	 * @param String $httpRequestClass class name of MWHttpRequest (needed for testing only)
 	 * @return bool success
 	 */
@@ -337,7 +339,7 @@ class MathMathML extends MathRenderer {
 	}
 
 	/**
-	 * @param boolean $noRender
+	 * @param bool $noRender
 	 * @return Title|string
 	 */
 	private function getFallbackImageUrl( $noRender = false ) {
@@ -355,7 +357,7 @@ class MathMathML extends MathRenderer {
 	/**
 	 * Helper function to correct the style information for a
 	 * linked SVG image.
-	 * @param string $style current style information to be updated
+	 * @param string &$style current style information to be updated
 	 */
 	public function correctSvgStyle( &$style ) {
 		if ( preg_match( '/style="([^"]*)"/', $this->getSvg(), $styles ) ) {
@@ -383,9 +385,9 @@ class MathMathML extends MathRenderer {
 
 	/**
 	 * Gets img tag for math image
-	 * @param boolean $noRender if true no rendering will be performed
+	 * @param bool $noRender if true no rendering will be performed
 	 * if the image is not stored in the database
-	 * @param boolean|string $classOverride if classOverride
+	 * @param bool|string $classOverride if classOverride
 	 * is false the class name will be calculated by getClassName
 	 * @return string XML the image html tag
 	 */
@@ -418,7 +420,7 @@ class MathMathML extends MathRenderer {
 
 	/**
 	 * Calculates the default class name for a math element
-	 * @param boolean $fallback
+	 * @param bool $fallback
 	 * @return string the class name
 	 */
 	private function getClassName( $fallback = false ) {

MathRenderer.php

@@ -40,13 +40,13 @@ abstract class MathRenderer {
 	protected $id = '';
 
 	// STATE OF THE CLASS INSTANCE
-	/** @var boolean has variable tex been security-checked */
+	/** @var bool has variable tex been security-checked */
 	protected $texSecure = false;
-	/** @var boolean has the mathematical content changed */
+	/** @var bool has the mathematical content changed */
 	protected $changed = false;
-	/** @var boolean is there a database entry for the mathematical content */
+	/** @var bool is there a database entry for the mathematical content */
 	protected $storedInDatabase = null;
-	/** @var boolean is there a request to purge the existing mathematical content */
+	/** @var bool is there a request to purge the existing mathematical content */
 	protected $purge = false;
 	/** @var string with last occurred error */
 	protected $lastError = '';
@@ -183,7 +183,7 @@ abstract class MathRenderer {
 	/**
 	 * Performs the rendering
 	 *
-	 * @return boolean if rendering was successful.
+	 * @return bool if rendering was successful.
 	 */
 	abstract public function render();
 
@@ -226,7 +226,7 @@ abstract class MathRenderer {
 
 	/**
 	 * Set the input hash (if user input tex is not available)
-	 * @param $md5
+	 * @param string $md5
 	 * @return string hash
 	 */
 	public function setMd5( $md5 ) {
@@ -407,6 +407,7 @@ abstract class MathRenderer {
 
 	/**
 	 * Writes cache. Writes the database entry if values were changed
+	 * @return bool
 	 */
 	public function writeCache() {
 		$logger = LoggerFactory::getInstance( 'Math' );
@@ -537,7 +538,7 @@ abstract class MathRenderer {
 	 * Sets purge. If set to true the render is forced to rerender and must not
 	 * use a cached version.
 	 * @param bool $purge
-	 * @return boolean
+	 * @return bool
 	 */
 	function setPurge( $purge = true ) {
 		$this->changed = true;
@@ -621,7 +622,7 @@ abstract class MathRenderer {
 	}
 
 	/**
-	 * @param string user defined ID
+	 * @param string $id user defined ID
 	 */
 	public function setID( $id ) {
 		// Changes in the ID affect the container for the math element on the current page

MathRestbaseInterface.php

@@ -18,7 +18,7 @@ class MathRestbaseInterface {
 	private $error;
 	private $mathoidStyle;
 	private $mml;
-	/** @var boolean is there a request to purge the existing mathematical content */
+	/** @var bool is there a request to purge the existing mathematical content */
 	private $purge = false;
 
 	/**
@@ -359,7 +359,7 @@ class MathRestbaseInterface {
 	}
 
 	/**
-	 * @param $response
+	 * @param array $response
 	 * @return bool
 	 */
 	public function evaluateRestbaseCheckResponse( $response ) {
@@ -436,8 +436,8 @@ class MathRestbaseInterface {
 	}
 
 	/**
-	 * @param $type
-	 * @param $body
+	 * @param string $type
+	 * @param string $body
 	 * @throws MWException
 	 */
 	public static function throwContentError( $type, $body ) {

MathTexvc.php

@@ -354,6 +354,7 @@ class MathTexvc extends MathRenderer {
 
 	/**
 	 * Overrides base class.  Writes to database, and if configured, squid.
+	 * @return bool
 	 */
 	public function writeCache() {
 		global $wgUseSquid;

MathWikidataHook.php

@@ -13,6 +13,7 @@ class MathWikidataHook {
 
 	/**
 	 * Add Datatype "Math" to the Wikibase Repository
+	 * @param array &$dataTypeDefinitions
 	 */
 	public static function onWikibaseRepoDataTypes( array &$dataTypeDefinitions ) {
 		global $wgMathEnableWikibaseDataType;
@@ -57,8 +58,9 @@ class MathWikidataHook {
 		];
 	}
 
-	/*
+	/**
 	 * Add Datatype "Math" to the Wikibase Client
+	 * @param array &$dataTypeDefinitions
 	 */
 	public static function onWikibaseClientDataTypes( array &$dataTypeDefinitions ) {
 		global $wgMathEnableWikibaseDataType;

composer.json

@@ -6,7 +6,7 @@
 	},
 	"scripts": {
 		"test": [
-			"parallel-lint . --exclude vendor",
+			"parallel-lint . --exclude vendor --exclude node_modules",
 			"phpcs -p -s"
 		],
 		"fix": [

phpcs.xml

@@ -1,12 +1,7 @@
 <?xml version="1.0"?>
 <ruleset>
 	<rule ref="./vendor/mediawiki/mediawiki-codesniffer/MediaWiki">
-		<exclude name="MediaWiki.Commenting.FunctionComment.DuplicateReturn" />
 		<exclude name="MediaWiki.Commenting.FunctionComment.MissingParamComment" />
-		<exclude name="MediaWiki.Commenting.FunctionComment.MissingParamName" />
-		<exclude name="MediaWiki.Commenting.FunctionComment.MissingParamTag" />
-		<exclude name="MediaWiki.Commenting.FunctionComment.MissingReturn" />
-		<exclude name="MediaWiki.Commenting.FunctionComment.ParamNameNoMatch" />
 		<exclude name="MediaWiki.Commenting.FunctionComment.WrongStyle" />
 		<exclude name="MediaWiki.Commenting.FunctionComment.MissingDocumentationProtected" />
 		<exclude name="MediaWiki.Commenting.FunctionComment.MissingDocumentationPublic" />

tests/MathMathMLTest.php

@@ -20,9 +20,9 @@ class MathMathMLTest extends MediaWikiTestCase {
 	/**
 	 * Set the mock values for the HTTP Mockup classes
 	 *
-	 * @param boolean $good
+	 * @param bool $good
 	 * @param mixed $html HTML of the error message or false if no error is present.
-	 * @param boolean $timeout true if
+	 * @param bool $timeout true if
 	 */
 	public static function setMockValues( $good, $html, $timeout ) {
 		self::$good = $good;