From 1254022153302c916ea92a95a434ddddf9776bf0 Mon Sep 17 00:00:00 2001 From: Umherirrender Date: Sat, 9 Sep 2017 20:10:12 +0200 Subject: [PATCH] Improve some parameter docs Change-Id: Idce2db0b489c19ec9b936cfc4ced3792e6f9711d --- FancyCaptcha/ApiFancyCaptchaReload.php | 1 + FancyCaptcha/FancyCaptcha.class.php | 26 ++++---- MathCaptcha/MathCaptcha.class.php | 15 +++-- QuestyCaptcha/QuestyCaptcha.class.php | 4 +- ReCaptcha/ReCaptcha.class.php | 10 +-- .../ReCaptchaNoCaptcha.class.php | 17 ++--- SimpleCaptcha/Captcha.php | 63 ++++++++++--------- includes/CaptchaStore.php | 12 ++-- includes/ConfirmEditHooks.php | 2 +- phpcs.xml | 5 -- 10 files changed, 81 insertions(+), 74 deletions(-) diff --git a/FancyCaptcha/ApiFancyCaptchaReload.php b/FancyCaptcha/ApiFancyCaptchaReload.php index d53d7baaa..f3e0d11be 100644 --- a/FancyCaptcha/ApiFancyCaptchaReload.php +++ b/FancyCaptcha/ApiFancyCaptchaReload.php @@ -23,6 +23,7 @@ class ApiFancyCaptchaReload extends ApiBase { /** * @see ApiBase::getExamplesMessages() + * @return array */ protected function getExamplesMessages() { return [ diff --git a/FancyCaptcha/FancyCaptcha.class.php b/FancyCaptcha/FancyCaptcha.class.php index a875254b1..c2477bf7f 100644 --- a/FancyCaptcha/FancyCaptcha.class.php +++ b/FancyCaptcha/FancyCaptcha.class.php @@ -81,7 +81,7 @@ class FancyCaptcha extends SimpleCaptcha { } /** - * @param array $resultArr + * @param array &$resultArr */ function addCaptchaAPI( &$resultArr ) { $info = $this->pickImage(); @@ -198,9 +198,9 @@ class FancyCaptcha extends SimpleCaptcha { } /** - * @param $directory string - * @param $levels integer - * @param $lockouts integer + * @param string $directory + * @param int $levels + * @param int &$lockouts * @return array|bool */ protected function pickImageDir( $directory, $levels, &$lockouts ) { @@ -251,8 +251,8 @@ class FancyCaptcha extends SimpleCaptcha { } /** - * @param $directory string - * @param $lockouts integer + * @param string $directory + * @param int &$lockouts * @return array|bool */ protected function pickImageFromDir( $directory, &$lockouts ) { @@ -293,9 +293,9 @@ class FancyCaptcha extends SimpleCaptcha { } /** - * @param $directory string - * @param $files array - * @param $lockouts integer + * @param string $directory + * @param array $files + * @param int &$lockouts * @return array|bool */ protected function pickImageFromList( $directory, array $files, &$lockouts ) { @@ -365,8 +365,8 @@ class FancyCaptcha extends SimpleCaptcha { } /** - * @param $salt string - * @param $hash string + * @param string $salt + * @param string $hash * @return string */ public function imagePath( $salt, $hash ) { @@ -382,7 +382,7 @@ class FancyCaptcha extends SimpleCaptcha { } /** - * @param $basename string + * @param string $basename * @return array (salt, hash) * @throws Exception */ @@ -440,7 +440,7 @@ class FancyCaptcha extends SimpleCaptcha { /** * @param array $requests * @param array $fieldInfo - * @param array $formDescriptor + * @param array &$formDescriptor * @param string $action */ public function onAuthChangeFormFields( diff --git a/MathCaptcha/MathCaptcha.class.php b/MathCaptcha/MathCaptcha.class.php index 4ee178d95..0c7dee0a6 100644 --- a/MathCaptcha/MathCaptcha.class.php +++ b/MathCaptcha/MathCaptcha.class.php @@ -15,7 +15,7 @@ class MathCaptcha extends SimpleCaptcha { } /** - * @param array $resultArr + * @param array &$resultArr */ function addCaptchaAPI( &$resultArr ) { list( $sum, $answer ) = $this->pickSum(); @@ -54,7 +54,10 @@ class MathCaptcha extends SimpleCaptcha { return [ 'html' => $form ]; } - /** Pick a random sum */ + /** + * Pick a random sum + * @return array + */ function pickSum() { $a = mt_rand( 0, 100 ); $b = mt_rand( 0, 10 ); @@ -64,7 +67,11 @@ class MathCaptcha extends SimpleCaptcha { return [ $sum, $ans ]; } - /** Fetch the math */ + /** + * Fetch the math + * @param int $sum + * @return string + */ function fetchMath( $sum ) { if ( class_exists( 'MathRenderer' ) ) { $math = MathRenderer::getRenderer( $sum, [], 'png' ); @@ -98,7 +105,7 @@ class MathCaptcha extends SimpleCaptcha { /** * @param array $requests * @param array $fieldInfo - * @param array $formDescriptor + * @param array &$formDescriptor * @param string $action */ public function onAuthChangeFormFields( array $requests, array $fieldInfo, diff --git a/QuestyCaptcha/QuestyCaptcha.class.php b/QuestyCaptcha/QuestyCaptcha.class.php index adc00bcb6..95da1021c 100644 --- a/QuestyCaptcha/QuestyCaptcha.class.php +++ b/QuestyCaptcha/QuestyCaptcha.class.php @@ -30,7 +30,7 @@ class QuestyCaptcha extends SimpleCaptcha { } /** - * @param array $resultArr + * @param array &$resultArr */ function addCaptchaAPI( &$resultArr ) { $captcha = $this->getCaptcha(); @@ -117,7 +117,7 @@ class QuestyCaptcha extends SimpleCaptcha { /** * @param array $requests * @param array $fieldInfo - * @param array $formDescriptor + * @param array &$formDescriptor * @param string $action */ public function onAuthChangeFormFields( array $requests, array $fieldInfo, diff --git a/ReCaptcha/ReCaptcha.class.php b/ReCaptcha/ReCaptcha.class.php index e2b22ade7..a62633e0b 100644 --- a/ReCaptcha/ReCaptcha.class.php +++ b/ReCaptcha/ReCaptcha.class.php @@ -13,6 +13,8 @@ class ReCaptcha extends SimpleCaptcha { /** * Displays the reCAPTCHA widget. * If $this->recaptcha_error is set, it will display an error in the widget. + * @param int $tabIndex + * @return array */ function getFormInformation( $tabIndex = 1 ) { global $wgReCaptchaPublicKey, $wgReCaptchaTheme; @@ -72,7 +74,7 @@ class ReCaptcha extends SimpleCaptcha { } /** - * @param array $resultArr + * @param array &$resultArr */ function addCaptchaAPI( &$resultArr ) { $resultArr['captcha'] = $this->describeCaptchaType(); @@ -92,8 +94,8 @@ class ReCaptcha extends SimpleCaptcha { } /** - * @param ApiBase $module - * @param array $params + * @param ApiBase &$module + * @param array &$params * @param int $flags * @return bool */ @@ -159,7 +161,7 @@ class ReCaptcha extends SimpleCaptcha { /** * @param array $requests * @param array $fieldInfo - * @param array $formDescriptor + * @param array &$formDescriptor * @param string $action */ public function onAuthChangeFormFields( diff --git a/ReCaptchaNoCaptcha/ReCaptchaNoCaptcha.class.php b/ReCaptchaNoCaptcha/ReCaptchaNoCaptcha.class.php index 15e1c108d..19aa10935 100644 --- a/ReCaptchaNoCaptcha/ReCaptchaNoCaptcha.class.php +++ b/ReCaptchaNoCaptcha/ReCaptchaNoCaptcha.class.php @@ -10,6 +10,7 @@ class ReCaptchaNoCaptcha extends SimpleCaptcha { private $error = null; /** * Get the captcha form. + * @param int $tabIndex * @return array */ function getFormInformation( $tabIndex = 1 ) { @@ -59,7 +60,7 @@ HTML; } /** - * @param $info + * @param Status|array|string $info */ protected function logCheckError( $info ) { if ( $info instanceof Status ) { @@ -91,8 +92,8 @@ HTML; * Based on reference implementation: * https://github.com/google/recaptcha#php * - * @param $_ mixed Not used (ReCaptcha v2 puts index and solution in a single string) - * @param $word string captcha solution + * @param mixed $_ Not used (ReCaptcha v2 puts index and solution in a single string) + * @param string $word captcha solution * @return bool */ function passCaptcha( $_, $word ) { @@ -131,7 +132,7 @@ HTML; } /** - * @param array $resultArr + * @param array &$resultArr */ function addCaptchaAPI( &$resultArr ) { $resultArr['captcha'] = $this->describeCaptchaType(); @@ -154,7 +155,7 @@ HTML; * Show a message asking the user to enter a captcha on edit * The result will be treated as wiki text * - * @param $action string Action being performed + * @param string $action Action being performed * @return string Wikitext */ public function getMessage( $action ) { @@ -166,8 +167,8 @@ HTML; } /** - * @param ApiBase $module - * @param array $params + * @param ApiBase &$module + * @param array &$params * @param int $flags * @return bool */ @@ -220,7 +221,7 @@ HTML; /** * @param array $requests * @param array $fieldInfo - * @param array $formDescriptor + * @param array &$formDescriptor * @param string $action */ public function onAuthChangeFormFields( diff --git a/SimpleCaptcha/Captcha.php b/SimpleCaptcha/Captcha.php index 66f508c96..d61a6c56e 100644 --- a/SimpleCaptcha/Captcha.php +++ b/SimpleCaptcha/Captcha.php @@ -38,7 +38,7 @@ class SimpleCaptcha { /** * Return the error from the last passCaptcha* call. * Not implemented but needed by some child classes. - * @return + * @return mixed */ public function getError() { return null; @@ -66,7 +66,7 @@ class SimpleCaptcha { } /** - * @param array $resultArr + * @param array &$resultArr */ function addCaptchaAPI( &$resultArr ) { $captcha = $this->getCaptcha(); @@ -186,8 +186,8 @@ class SimpleCaptcha { /** * Show error message for missing or incorrect captcha on EditPage. - * @param EditPage $editPage - * @param OutputPage $out + * @param EditPage &$editPage + * @param OutputPage &$out */ function showEditFormFields( &$editPage, &$out ) { $page = $editPage->getArticle()->getPage(); @@ -223,7 +223,7 @@ class SimpleCaptcha { * Show a message asking the user to enter a captcha on edit * The result will be treated as wiki text * - * @param $action string Action being performed + * @param string $action Action being performed * @return Message */ public function getMessage( $action ) { @@ -239,7 +239,7 @@ class SimpleCaptcha { /** * Inject whazawhoo * @fixme if multiple thingies insert a header, could break - * @param $form HTMLForm + * @param HTMLForm &$form * @return bool true to keep running callbacks */ function injectEmailUser( &$form ) { @@ -326,7 +326,7 @@ class SimpleCaptcha { /** * Is the per-user captcha triggered? * - * @param $u User|String User object, or name + * @param User|string $u User object, or name * @return bool|null False: no, null: no, but it will be triggered next time */ public function isBadLoginPerUserTriggered( $u ) { @@ -478,10 +478,10 @@ class SimpleCaptcha { /** * @param WikiPage $page - * @param $content Content|string - * @param $section string + * @param Content|string $content + * @param string $section * @param IContextSource $context - * @param oldtext string The content of the revision prior to $content When + * @param string $oldtext The content of the revision prior to $content When * null this will be loaded from the database. * @return bool true if the captcha should run */ @@ -623,7 +623,7 @@ class SimpleCaptcha { /** * Filter callback function for URL whitelisting - * @param $url string to check + * @param string $url string to check * @return bool true if unknown, false if whitelisted * @access private */ @@ -654,7 +654,7 @@ class SimpleCaptcha { /** * Build regex from whitelist - * @param $lines string from [[MediaWiki:Captcha-addurl-whitelist]] + * @param string $lines string from [[MediaWiki:Captcha-addurl-whitelist]] * @return array Regexes * @access private */ @@ -728,7 +728,7 @@ class SimpleCaptcha { /** * Load external links from the externallinks table - * @param $title Title + * @param Title $title * @return array */ function getLinksFromTracker( $title ) { @@ -746,8 +746,8 @@ class SimpleCaptcha { /** * Backend function for confirmEditMerged() * @param WikiPage $page - * @param $newtext string - * @param $section + * @param string $newtext + * @param string $section * @param IContextSource $context * @return bool false if the CAPTCHA is rejected, true otherwise */ @@ -778,9 +778,9 @@ class SimpleCaptcha { * @param RequestContext $context * @param Content $content * @param Status $status - * @param $summary - * @param $user - * @param $minorEdit + * @param string $summary + * @param User $user + * @param bool $minorEdit * @return bool */ function confirmEditMerged( $context, $content, $status, $summary, $user, $minorEdit ) { @@ -851,12 +851,12 @@ class SimpleCaptcha { /** * Check the captcha on Special:EmailUser - * @param $from MailAddress - * @param $to MailAddress - * @param $subject String - * @param $text String - * @param $error String reference - * @return Bool true to continue saving, false to abort and show a captcha form + * @param MailAddress $from + * @param MailAddress $to + * @param string $subject + * @param string $text + * @param string &$error + * @return bool true to continue saving, false to abort and show a captcha form */ function confirmEmailUser( $from, $to, $subject, $text, &$error ) { global $wgCaptchaTriggers, $wgUser, $wgRequest; @@ -886,7 +886,7 @@ class SimpleCaptcha { } /** - * @param $module ApiBase + * @param ApiBase $module * @return bool */ protected function isAPICaptchaModule( $module ) { @@ -894,9 +894,9 @@ class SimpleCaptcha { } /** - * @param $module ApiBase - * @param $params array - * @param $flags int + * @param ApiBase &$module + * @param array &$params + * @param int $flags * @return bool */ public function APIGetAllowedParams( &$module, &$params, $flags ) { @@ -1047,6 +1047,7 @@ class SimpleCaptcha { /** * Clear out existing captcha info from the session, to ensure * it can't be reused. + * @param string $index */ public function clearCaptcha( $index ) { CaptchaStore::get()->clear( $index ); @@ -1079,8 +1080,8 @@ class SimpleCaptcha { /** * Extract a list of all recognized HTTP links in the text. - * @param $title Title - * @param $text string + * @param Title $title + * @param string $text * @return array of strings */ function findLinks( $title, $text ) { @@ -1118,7 +1119,7 @@ class SimpleCaptcha { * Modify the apprearance of the captcha field * @param AuthenticationRequest[] $requests * @param array $fieldInfo Field description as given by AuthenticationRequest::mergeFieldInfo - * @param array $formDescriptor A form descriptor suitable for the HTMLForm constructor + * @param array &$formDescriptor A form descriptor suitable for the HTMLForm constructor * @param string $action One of the AuthManager::ACTION_* constants */ public function onAuthChangeFormFields( diff --git a/includes/CaptchaStore.php b/includes/CaptchaStore.php index 5a78e466f..9eb52005d 100644 --- a/includes/CaptchaStore.php +++ b/includes/CaptchaStore.php @@ -5,27 +5,27 @@ use MediaWiki\Session\SessionManager; abstract class CaptchaStore { /** * Store the correct answer for a given captcha - * @param $index String - * @param $info String the captcha result + * @param string $index + * @param string $info the captcha result */ abstract public function store( $index, $info ); /** * Retrieve the answer for a given captcha - * @param $index String - * @return String|false + * @param string $index + * @return string|false */ abstract public function retrieve( $index ); /** * Delete a result once the captcha has been used, so it cannot be reused - * @param $index + * @param string $index */ abstract public function clear( $index ); /** * Whether this type of CaptchaStore needs cookies - * @return Bool + * @return bool */ abstract public function cookiesNeeded(); diff --git a/includes/ConfirmEditHooks.php b/includes/ConfirmEditHooks.php index aa2557698..d2dcc555b 100644 --- a/includes/ConfirmEditHooks.php +++ b/includes/ConfirmEditHooks.php @@ -110,7 +110,7 @@ class ConfirmEditHooks { * * @param Title $title * @param User $user - * @param $whitelisted + * @param bool &$whitelisted */ public static function onTitleReadWhitelist( Title $title, User $user, &$whitelisted ) { $image = SpecialPage::getTitleFor( 'Captcha', 'image' ); diff --git a/phpcs.xml b/phpcs.xml index bc77fda20..a60b550a7 100644 --- a/phpcs.xml +++ b/phpcs.xml @@ -3,11 +3,6 @@ - - - - -