From 6419dc7e26b5d9752b10a091e18a9127b6c6ac81 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Thiemo=20M=C3=A4ttig?= Date: Tue, 8 Apr 2014 12:22:43 +0200 Subject: [PATCH] WebInstaller inline documentation cleanup This is a follow-up to Ide17d5af13c416c62a40029848ac17ba24eb5563. However, I could not fix the "minor style" issue mentioned there because this would make the line to long. I fixed lots and lots of other issues instead, e.g.: * "void" isn't a thing. Added "return null" instead. * Removed documentation that said "a constructor is a constructor". * Use "string[]" and such instead of "array" if possible. Change-Id: I9658c2af58862f1d634cf1b2ba4c9d0f27ee7608 --- includes/installer/WebInstaller.php | 74 ++++++---- includes/installer/WebInstallerOutput.php | 31 +++- includes/installer/WebInstallerPage.php | 165 ++++++++++++++++++++-- 3 files changed, 226 insertions(+), 44 deletions(-) diff --git a/includes/installer/WebInstaller.php b/includes/installer/WebInstaller.php index 79fdc99319..42672ca353 100644 --- a/includes/installer/WebInstaller.php +++ b/includes/installer/WebInstaller.php @@ -44,13 +44,14 @@ class WebInstaller extends Installer { /** * Cached session array. * - * @var array + * @var array[] */ protected $session; /** * Captured PHP error text. Temporary. - * @var array + * + * @var string[] */ protected $phpErrors; @@ -61,7 +62,8 @@ class WebInstaller extends Installer { * * Add it to this WebInstaller::$pageSequence property * * Add a "config-page-" message * * Add a "WebInstaller_" class - * @var array + * + * @var string[] */ public $pageSequence = array( 'Language', @@ -78,7 +80,8 @@ class WebInstaller extends Installer { /** * Out of sequence pages, selectable by the user at any time. - * @var array + * + * @var string[] */ protected $otherPages = array( 'Restart', @@ -91,7 +94,8 @@ class WebInstaller extends Installer { /** * Array of pages which have declared that they have been submitted, have validated * their input, and need no further processing. - * @var array + * + * @var bool[] */ protected $happyPages; @@ -99,24 +103,28 @@ class WebInstaller extends Installer { * List of "skipped" pages. These are pages that will automatically continue * to the next page on any GET request. To avoid breaking the "back" button, * they need to be skipped during a back operation. - * @var array + * + * @var bool[] */ protected $skippedPages; /** * Flag indicating that session data may have been lost. + * * @var bool */ public $showSessionWarning = false; /** * Numeric index of the page we're on + * * @var int */ protected $tabIndex = 1; /** * Name of the page we're on + * * @var string */ protected $currentPageName; @@ -140,9 +148,9 @@ class WebInstaller extends Installer { /** * Main entry point. * - * @param array $session initial session array + * @param array[] $session initial session array * - * @return array New session array + * @return array[] New session array */ public function execute( array $session ) { $this->session = $session; @@ -396,7 +404,8 @@ class WebInstaller extends Installer { /** * Temporary error handler for session start debugging. - * @param $errno + * + * @param int $errno Unused * @param string $errstr */ public function errorHandler( $errno, $errstr ) { @@ -406,7 +415,7 @@ class WebInstaller extends Installer { /** * Clean up from execute() * - * @return array + * @return array[] */ public function finish() { $this->output->output(); @@ -430,7 +439,8 @@ class WebInstaller extends Installer { /** * Get a URL for submission back to the same script. * - * @param array $query + * @param string[] $query + * * @return string */ public function getUrl( $query = array() ) { @@ -461,8 +471,9 @@ class WebInstaller extends Installer { * Get a session variable. * * @param string $name - * @param $default - * @return null + * @param array $default + * + * @return array */ public function getSession( $name, $default = null ) { if ( !isset( $this->session[$name] ) ) { @@ -474,6 +485,7 @@ class WebInstaller extends Installer { /** * Set a session variable. + * * @param string $name Key for the variable * @param mixed $value */ @@ -483,6 +495,7 @@ class WebInstaller extends Installer { /** * Get the next tabindex attribute value. + * * @return int */ public function nextTabIndex() { @@ -770,7 +783,7 @@ class WebInstaller extends Installer { /** * Get a labelled text box to configure a variable. * - * @param array $params + * @param mixed[] $params * Parameters are: * var: The variable to be configured (required) * label: The message name for the label (required) @@ -817,7 +830,7 @@ class WebInstaller extends Installer { /** * Get a labelled textarea to configure a variable * - * @param array $params + * @param mixed[] $params * Parameters are: * var: The variable to be configured (required) * label: The message name for the label (required) @@ -866,7 +879,7 @@ class WebInstaller extends Installer { * Get a labelled password box to configure a variable. * * Implements password hiding - * @param array $params + * @param mixed[] $params * Parameters are: * var: The variable to be configured (required) * label: The message name for the label (required) @@ -895,7 +908,7 @@ class WebInstaller extends Installer { /** * Get a labelled checkbox to configure a boolean variable. * - * @param array $params + * @param mixed[] $params * Parameters are: * var: The variable to be configured (required) * label: The message name for the label (required) @@ -946,7 +959,7 @@ class WebInstaller extends Installer { /** * Get a set of labelled radio buttons. * - * @param array $params + * @param mixed[] $params * Parameters are: * var: The variable to be configured (required) * label: The message name for the label (required) @@ -1033,10 +1046,10 @@ class WebInstaller extends Installer { * Assumes that variables containing "password" in the name are (potentially * fake) passwords. * - * @param array $varNames + * @param string[] $varNames * @param string $prefix The prefix added to variables to obtain form names * - * @return array + * @return string[] */ public function setVarsFromRequest( $varNames, $prefix = 'config_' ) { $newValues = array(); @@ -1063,7 +1076,8 @@ class WebInstaller extends Installer { /** * Helper for Installer::docLink() * - * @param $page + * @param string $page + * * @return string */ protected function getDocUrl( $page ) { @@ -1079,9 +1093,10 @@ class WebInstaller extends Installer { /** * Extension tag hook for a documentation link. * - * @param $linkText - * @param $attribs - * @param $parser + * @param string $linkText + * @param string[] $attribs + * @param Parser $parser Unused + * * @return string */ public function docLink( $linkText, $attribs, $parser ) { @@ -1095,9 +1110,10 @@ class WebInstaller extends Installer { /** * Helper for "Download LocalSettings" link on WebInstall_Complete * - * @param $text - * @param $attribs - * @param $parser + * @param string $text Unused + * @param string[] $attribs Unused + * @param Parser $parser Unused + * * @return string Html for download link */ public function downloadLinkHook( $text, $attribs, $parser ) { @@ -1138,7 +1154,11 @@ class WebInstaller extends Installer { return parent::envCheckPath(); } + /** + * @return String + */ protected function envGetDefaultServer() { return WebRequest::detectServer(); } + } diff --git a/includes/installer/WebInstallerOutput.php b/includes/installer/WebInstallerOutput.php index e05a3d4d3e..a5e3c8b03a 100644 --- a/includes/installer/WebInstallerOutput.php +++ b/includes/installer/WebInstallerOutput.php @@ -33,6 +33,7 @@ * @since 1.17 */ class WebInstallerOutput { + /** * The WebInstaller object this WebInstallerOutput is used by. * @@ -52,6 +53,9 @@ class WebInstallerOutput { */ private $headerDone = false; + /** + * @var string + */ public $redirectTarget; /** @@ -69,27 +73,39 @@ class WebInstallerOutput { private $useShortHeader = false; /** - * Constructor. - * - * @param $parent WebInstaller + * @param WebInstaller $parent */ public function __construct( WebInstaller $parent ) { $this->parent = $parent; } + /** + * @param string $html + */ public function addHTML( $html ) { $this->contents .= $html; $this->flush(); } + /** + * @param string $text + */ public function addWikiText( $text ) { $this->addHTML( $this->parent->parse( $text ) ); } + /** + * @param string $html + */ public function addHTMLNoFlush( $html ) { $this->contents .= $html; } + /** + * @param string $url + * + * @throws MWException + */ public function redirect( $url ) { if ( $this->headerDone ) { throw new MWException( __METHOD__ . ' called after sending headers' ); @@ -110,6 +126,7 @@ class WebInstallerOutput { * and not properly handling such details as media types in module definitions. * * @param string $dir 'ltr' or 'rtl' + * * @return String */ public function getCSS( $dir ) { @@ -192,6 +209,7 @@ class WebInstallerOutput { /** * "" to index.php?css=foobar for the "" + * * @return String */ private function getCssUrl() { @@ -236,7 +254,7 @@ class WebInstallerOutput { } /** - * @return array + * @return string[] */ public function getHeadAttribs() { return array( @@ -247,6 +265,7 @@ class WebInstallerOutput { /** * Get whether the header has been output + * * @return bool */ public function headerDone() { @@ -341,7 +360,11 @@ class WebInstallerOutput { echo wfMessage( 'config-title', $wgVersion )->escaped(); } + /** + * @return string + */ public function getJQuery() { return Html::linkedScript( "../resources/jquery/jquery.js" ); } + } diff --git a/includes/installer/WebInstallerPage.php b/includes/installer/WebInstallerPage.php index 69a460a859..3b3473b06d 100644 --- a/includes/installer/WebInstallerPage.php +++ b/includes/installer/WebInstallerPage.php @@ -36,12 +36,13 @@ abstract class WebInstallerPage { */ public $parent; + /** + * @return string + */ abstract public function execute(); /** - * Constructor. - * - * @param $parent WebInstaller + * @param WebInstaller $parent */ public function __construct( WebInstaller $parent ) { $this->parent = $parent; @@ -51,12 +52,16 @@ abstract class WebInstallerPage { * Is this a slow-running page in the installer? If so, WebInstaller will * set_time_limit(0) before calling execute(). Right now this only applies * to Install and Upgrade pages - * @return bool + * + * @return bool Always false in this default implementation. */ public function isSlow() { return false; } + /** + * @param string $html + */ public function addHTML( $html ) { $this->parent->output->addHTML( $html ); } @@ -124,18 +129,33 @@ abstract class WebInstallerPage { $this->addHTML( $s ); } + /** + * @return string + */ public function getName() { return str_replace( 'WebInstaller_', '', get_class( $this ) ); } + /** + * @return string + */ protected function getId() { return array_search( $this->getName(), $this->parent->pageSequence ); } + /** + * @param string $var + * + * @return mixed + */ public function getVar( $var ) { return $this->parent->getVar( $var ); } + /** + * @param string $name + * @param mixed $value + */ public function setVar( $name, $value ) { $this->parent->setVar( $name, $value ); } @@ -175,16 +195,21 @@ abstract class WebInstallerPage { } /** - * Opposite to startLiveBox() + * Opposite to WebInstallerPage::startLiveBox */ protected function endLiveBox() { $this->addHTML( ' ' ); $this->parent->output->flush(); } + } class WebInstaller_Language extends WebInstallerPage { + + /** + * @return string|null + */ public function execute() { global $wgLang; $r = $this->parent->request; @@ -244,15 +269,18 @@ class WebInstaller_Language extends WebInstallerPage { $this->parent->getHelpBox( 'config-wiki-language-help' ) ); $this->addHTML( $s ); $this->endForm( 'continue', false ); + + return null; } /** * Get a "