From 8a7d5c154b3df2c4b5b83df1f9caa5cf7ed452ae Mon Sep 17 00:00:00 2001 From: Siebrand Mazeland Date: Tue, 8 Oct 2013 18:20:08 +0200 Subject: [PATCH] Update documentation Change-Id: Ia8ca4f3ab49e8a437830a9d15d013e9ddb0ea3ab --- includes/installer/DatabaseInstaller.php | 8 ++- includes/installer/DatabaseUpdater.php | 71 ++++++++++++------------ includes/installer/Installer.php | 9 ++- includes/installer/MysqlUpdater.php | 15 ++--- includes/installer/WebInstaller.php | 60 ++++++++++---------- 5 files changed, 86 insertions(+), 77 deletions(-) diff --git a/includes/installer/DatabaseInstaller.php b/includes/installer/DatabaseInstaller.php index 0110ac52f6..43d90e5561 100644 --- a/includes/installer/DatabaseInstaller.php +++ b/includes/installer/DatabaseInstaller.php @@ -438,6 +438,10 @@ abstract class DatabaseInstaller { /** * Get a labelled checkbox to configure a local boolean variable. * + * @param string $var + * @param string $label + * @param array $attribs Optional. + * @param string $helpData Optional. * @return string */ public function getCheckBox( $var, $label, $attribs = array(), $helpData = "" ) { @@ -544,8 +548,8 @@ abstract class DatabaseInstaller { /** * Get a standard web-user fieldset - * @param string $noCreateMsg Message to display instead of the creation checkbox. - * Set this to false to show a creation checkbox. + * @param string|bool $noCreateMsg Message to display instead of the creation checkbox. + * Set this to false to show a creation checkbox (default). * * @return String */ diff --git a/includes/installer/DatabaseUpdater.php b/includes/installer/DatabaseUpdater.php index 267b6c5a2c..4f1da708f0 100644 --- a/includes/installer/DatabaseUpdater.php +++ b/includes/installer/DatabaseUpdater.php @@ -77,7 +77,7 @@ abstract class DatabaseUpdater { /** * File handle for SQL output. * - * @var Filehandle + * @var resource */ protected $fileHandle = null; @@ -91,9 +91,9 @@ abstract class DatabaseUpdater { /** * Constructor * - * @param $db DatabaseBase object to perform updates on + * @param DatabaseBase $db To perform updates on * @param bool $shared Whether to perform updates on shared tables - * @param $maintenance Maintenance Maintenance object which created us + * @param Maintenance $maintenance Maintenance object which created us */ protected function __construct( DatabaseBase &$db, $shared, Maintenance $maintenance = null ) { $this->db = $db; @@ -199,7 +199,7 @@ abstract class DatabaseUpdater { * * @since 1.17 * - * @param array $update the update to run. Format is the following: + * @param array $update The update to run. Format is the following: * first item is the callback function, it also can be a * simple string with the name of a function in this class, * following elements are parameters to the function. @@ -383,7 +383,7 @@ abstract class DatabaseUpdater { /** * Do all the updates * - * @param array $what what updates to perform + * @param array $what What updates to perform */ public function doUpdates( $what = array( 'core', 'extensions', 'stats' ) ) { global $wgVersion; @@ -418,7 +418,7 @@ abstract class DatabaseUpdater { * Helper function for doUpdates() * * @param array $updates of updates to run - * @param $passSelf Boolean: whether to pass this object we calling external + * @param bool $passSelf Whether to pass this object we calling external * functions */ private function runUpdates( array $updates, $passSelf ) { @@ -445,8 +445,8 @@ abstract class DatabaseUpdater { } /** - * @param $version - * @param $updates array + * @param string $version + * @param array $updates */ protected function setAppliedUpdates( $version, $updates = array() ) { $this->db->clearFlag( DBO_DDLMODE ); @@ -465,7 +465,6 @@ abstract class DatabaseUpdater { * Obviously, only use this for updates that occur after the updatelog table was * created! * @param string $key Name of the key to check for - * * @return bool */ public function updateRowExists( $key ) { @@ -484,7 +483,7 @@ abstract class DatabaseUpdater { * Obviously, only use this for updates that occur after the updatelog table was * created! * @param string $key Name of key to insert - * @param string $val [optional] value to insert along with the key + * @param string $val [optional] Value to insert along with the key */ public function insertUpdateRow( $key, $val = null ) { $this->db->clearFlag( DBO_DDLMODE ); @@ -514,7 +513,7 @@ abstract class DatabaseUpdater { * Updates will be prevented if the table is a shared table and it is not * specified to run updates on shared tables. * - * @param string $name table name + * @param string $name Table name * @return bool */ protected function doTable( $name ) { @@ -579,7 +578,7 @@ abstract class DatabaseUpdater { * 1.13...) with the values being arrays of updates, identical to how * updaters.inc did it (for now) * - * @return Array + * @return array */ abstract protected function getCoreUpdateList(); @@ -600,8 +599,8 @@ abstract class DatabaseUpdater { * * This is used as a callback for for sourceLine(). * - * @param string $line text to append to the file - * @return Boolean false to skip actually executing the file + * @param string $line Text to append to the file + * @return bool False to skip actually executing the file * @throws MWException */ public function appendLine( $line ) { @@ -619,7 +618,7 @@ abstract class DatabaseUpdater { * @param string $path Path to the patch file * @param $isFullPath Boolean Whether to treat $path as a relative or not * @param string $msg Description of the patch - * @return boolean false if patch is skipped. + * @return bool False if patch is skipped. */ protected function applyPatch( $path, $isFullPath = false, $msg = null ) { if ( $msg === null ) { @@ -651,8 +650,8 @@ abstract class DatabaseUpdater { * * @param string $name Name of the new table * @param string $patch Path to the patch file - * @param $fullpath Boolean Whether to treat $patch path as a relative or not - * @return Boolean false if this was skipped because schema changes are skipped + * @param bool $fullpath Whether to treat $patch path as a relative or not + * @return bool False if this was skipped because schema changes are skipped */ protected function addTable( $name, $patch, $fullpath = false ) { if ( !$this->doTable( $name ) ) { @@ -674,8 +673,8 @@ abstract class DatabaseUpdater { * @param string $table Name of the table to modify * @param string $field Name of the new field * @param string $patch Path to the patch file - * @param $fullpath Boolean Whether to treat $patch path as a relative or not - * @return Boolean false if this was skipped because schema changes are skipped + * @param bool $fullpath Whether to treat $patch path as a relative or not + * @return bool False if this was skipped because schema changes are skipped */ protected function addField( $table, $field, $patch, $fullpath = false ) { if ( !$this->doTable( $table ) ) { @@ -699,8 +698,8 @@ abstract class DatabaseUpdater { * @param string $table Name of the table to modify * @param string $index Name of the new index * @param string $patch Path to the patch file - * @param $fullpath Boolean Whether to treat $patch path as a relative or not - * @return Boolean false if this was skipped because schema changes are skipped + * @param bool $fullpath Whether to treat $patch path as a relative or not + * @return bool False if this was skipped because schema changes are skipped */ protected function addIndex( $table, $index, $patch, $fullpath = false ) { if ( !$this->doTable( $table ) ) { @@ -724,8 +723,8 @@ abstract class DatabaseUpdater { * @param string $table Name of the table to modify * @param string $field Name of the old field * @param string $patch Path to the patch file - * @param $fullpath Boolean Whether to treat $patch path as a relative or not - * @return Boolean false if this was skipped because schema changes are skipped + * @param bool $fullpath Whether to treat $patch path as a relative or not + * @return bool False if this was skipped because schema changes are skipped */ protected function dropField( $table, $field, $patch, $fullpath = false ) { if ( !$this->doTable( $table ) ) { @@ -747,8 +746,8 @@ abstract class DatabaseUpdater { * @param string $table Name of the table to modify * @param string $index Name of the index * @param string $patch Path to the patch file - * @param $fullpath Boolean: Whether to treat $patch path as a relative or not - * @return Boolean false if this was skipped because schema changes are skipped + * @param bool $fullpath Whether to treat $patch path as a relative or not + * @return bool False if this was skipped because schema changes are skipped */ protected function dropIndex( $table, $index, $patch, $fullpath = false ) { if ( !$this->doTable( $table ) ) { @@ -773,8 +772,8 @@ abstract class DatabaseUpdater { * @param $skipBothIndexExistWarning Boolean: Whether to warn if both the * old and the new indexes exist. * @param string $patch Path to the patch file - * @param $fullpath Boolean: Whether to treat $patch path as a relative or not - * @return Boolean false if this was skipped because schema changes are skipped + * @param bool $fullpath Whether to treat $patch path as a relative or not + * @return bool False if this was skipped because schema changes are skipped */ protected function renameIndex( $table, $oldIndex, $newIndex, $skipBothIndexExistWarning, $patch, $fullpath = false @@ -825,10 +824,10 @@ abstract class DatabaseUpdater { * * Public @since 1.20 * - * @param $table string - * @param $patch string|false - * @param $fullpath bool - * @return Boolean false if this was skipped because schema changes are skipped + * @param string $table Table to drop. + * @param string|bool $patch String of patch file that will drop the table. Default: false. + * @param bool $fullpath Whether $patch is a full path. Default: false. + * @return bool False if this was skipped because schema changes are skipped */ public function dropTable( $table, $patch = false, $fullpath = false ) { if ( !$this->doTable( $table ) ) { @@ -855,11 +854,11 @@ abstract class DatabaseUpdater { /** * Modify an existing field * - * @param string $table name of the table to which the field belongs - * @param string $field name of the field to modify - * @param string $patch path to the patch file - * @param $fullpath Boolean: whether to treat $patch path as a relative or not - * @return Boolean false if this was skipped because schema changes are skipped + * @param string $table Name of the table to which the field belongs + * @param string $field Name of the field to modify + * @param string $patch Path to the patch file + * @param bool $fullpath Whether to treat $patch path as a relative or not + * @return bool False if this was skipped because schema changes are skipped */ public function modifyField( $table, $field, $patch, $fullpath = false ) { if ( !$this->doTable( $table ) ) { diff --git a/includes/installer/Installer.php b/includes/installer/Installer.php index 2f45005608..e6b0fd3323 100644 --- a/includes/installer/Installer.php +++ b/includes/installer/Installer.php @@ -1301,8 +1301,13 @@ abstract class Installer { /** * Same as locateExecutable(), but checks in getPossibleBinPaths() by default * @see locateExecutable() - * @param $names - * @param $versionInfo bool + * @param array $names Array of possible names. + * @param array|bool $versionInfo Default: false or array with two members: + * 0 => Command to run for version check, with $1 for the full executable name + * 1 => String to compare the output with + * + * If $versionInfo is not false, only executables with a version + * matching $versionInfo[1] will be returned. * @return bool|string */ public static function locateExecutableInDefaultPaths( $names, $versionInfo = false ) { diff --git a/includes/installer/MysqlUpdater.php b/includes/installer/MysqlUpdater.php index 059407348c..17c7577ad1 100644 --- a/includes/installer/MysqlUpdater.php +++ b/includes/installer/MysqlUpdater.php @@ -247,9 +247,10 @@ class MysqlUpdater extends DatabaseUpdater { * 1.4 betas were missing the 'binary' marker from logging.log_title, * which causes a collation mismatch error on joins in MySQL 4.1. * - * @param string $table table name - * @param string $field field name to check - * @param string $patchFile path to the patch to correct the field + * @param string $table Table name + * @param string $field Field name to check + * @param string $patchFile Path to the patch to correct the field + * @return bool */ protected function checkBin( $table, $field, $patchFile ) { if ( !$this->doTable( $table ) ) { @@ -267,10 +268,10 @@ class MysqlUpdater extends DatabaseUpdater { /** * Check whether an index contain a field * - * @param string $table table name - * @param string $index index name to check - * @param string $field field that should be in the index - * @return Boolean + * @param string $table Table name + * @param string $index Index name to check + * @param string $field Field that should be in the index + * @return bool */ protected function indexHasField( $table, $index, $field ) { if ( !$this->doTable( $table ) ) { diff --git a/includes/installer/WebInstaller.php b/includes/installer/WebInstaller.php index e23edf5ebf..53cb7dc519 100644 --- a/includes/installer/WebInstaller.php +++ b/includes/installer/WebInstaller.php @@ -124,7 +124,7 @@ class WebInstaller extends Installer { /** * Constructor. * - * @param $request WebRequest + * @param WebRequest $request */ public function __construct( WebRequest $request ) { parent::__construct(); @@ -142,7 +142,7 @@ class WebInstaller extends Installer { * * @param array $session initial session array * - * @return Array: new session array + * @return array New session array */ public function execute( array $session ) { $this->session = $session; @@ -391,7 +391,7 @@ class WebInstaller extends Installer { /** * Temporary error handler for session start debugging. * @param $errno - * @param $errstr string + * @param string $errstr */ public function errorHandler( $errno, $errstr ) { $this->phpErrors[] = $errstr; @@ -424,7 +424,7 @@ class WebInstaller extends Installer { /** * Get a URL for submission back to the same script. * - * @param $query array + * @param array $query * @return string */ public function getUrl( $query = array() ) { @@ -442,7 +442,7 @@ class WebInstaller extends Installer { /** * Get a WebInstallerPage by name. * - * @param $pageName String + * @param string $pageName * @return WebInstallerPage */ public function getPageByName( $pageName ) { @@ -454,7 +454,7 @@ class WebInstaller extends Installer { /** * Get a session variable. * - * @param $name String + * @param string $name * @param $default * @return null */ @@ -468,8 +468,8 @@ class WebInstaller extends Installer { /** * Set a session variable. - * @param string $name key for the variable - * @param $value Mixed + * @param string $name Key for the variable + * @param mixed $value */ public function setSession( $name, $value ) { $this->session[$name] = $value; @@ -523,7 +523,7 @@ class WebInstaller extends Installer { /** * Called by execute() before page output starts, to show a page list. * - * @param $currentPageName string + * @param string $currentPageName */ private function startPageWrapper( $currentPageName ) { $s = "
\n"; @@ -563,9 +563,9 @@ class WebInstaller extends Installer { /** * Get a list item for the page list. * - * @param $pageName string - * @param $enabled boolean - * @param $currentPageName string + * @param string $pageName + * @param bool $enabled + * @param string $currentPageName * * @return string */ @@ -630,7 +630,7 @@ class WebInstaller extends Installer { /** * Get HTML for an error box with an icon. * - * @param string $text wikitext, get this with wfMessage()->plain() + * @param string $text Wikitext, get this with wfMessage()->plain() * * @return string */ @@ -641,7 +641,7 @@ class WebInstaller extends Installer { /** * Get HTML for a warning box with an icon. * - * @param string $text wikitext, get this with wfMessage()->plain() + * @param string $text Wikitext, get this with wfMessage()->plain() * * @return string */ @@ -652,9 +652,9 @@ class WebInstaller extends Installer { /** * Get HTML for an info box with an icon. * - * @param string $text wikitext, get this with wfMessage()->plain() - * @param string $icon icon name, file in skins/common/images - * @param string $class additional class name to add to the wrapper div + * @param string $text Wikitext, get this with wfMessage()->plain() + * @param string|bool $icon Icon name, file in skins/common/images. Default: false + * @param string|bool $class Additional class name to add to the wrapper div. Default: false. * * @return string */ @@ -691,7 +691,7 @@ class WebInstaller extends Installer { /** * Output a help box. - * @param string $msg key for wfMessage() + * @param string $msg Key for wfMessage() */ public function showHelpBox( $msg /*, ... */ ) { $args = func_get_args(); @@ -703,7 +703,7 @@ class WebInstaller extends Installer { * Show a short informational message. * Output looks like a list. * - * @param $msg string + * @param string $msg */ public function showMessage( $msg /*, ... */ ) { $args = func_get_args(); @@ -715,7 +715,7 @@ class WebInstaller extends Installer { } /** - * @param $status Status + * @param Status $status */ public function showStatusMessage( Status $status ) { $errors = array_merge( $status->getErrorsArray(), $status->getWarningsArray() ); @@ -731,7 +731,7 @@ class WebInstaller extends Installer { * @param $msg * @param $forId * @param $contents - * @param $helpData string + * @param string $helpData * @return string */ public function label( $msg, $forId, $contents, $helpData = "" ) { @@ -764,7 +764,7 @@ class WebInstaller extends Installer { /** * Get a labelled text box to configure a variable. * - * @param $params Array + * @param array $params * Parameters are: * var: The variable to be configured (required) * label: The message name for the label (required) @@ -811,7 +811,7 @@ class WebInstaller extends Installer { /** * Get a labelled textarea to configure a variable * - * @param $params Array + * @param array $params * Parameters are: * var: The variable to be configured (required) * label: The message name for the label (required) @@ -860,7 +860,7 @@ class WebInstaller extends Installer { * Get a labelled password box to configure a variable. * * Implements password hiding - * @param $params Array + * @param array $params * Parameters are: * var: The variable to be configured (required) * label: The message name for the label (required) @@ -889,7 +889,7 @@ class WebInstaller extends Installer { /** * Get a labelled checkbox to configure a boolean variable. * - * @param $params Array + * @param array $params * Parameters are: * var: The variable to be configured (required) * label: The message name for the label (required) @@ -940,7 +940,7 @@ class WebInstaller extends Installer { /** * Get a set of labelled radio buttons. * - * @param $params Array + * @param array $params * Parameters are: * var: The variable to be configured (required) * label: The message name for the label (required) @@ -1006,7 +1006,7 @@ class WebInstaller extends Installer { /** * Output an error or warning box using a Status object. * - * @param $status Status + * @param Status $status */ public function showStatusBox( $status ) { if ( !$status->isGood() ) { @@ -1027,8 +1027,8 @@ class WebInstaller extends Installer { * Assumes that variables containing "password" in the name are (potentially * fake) passwords. * - * @param $varNames Array - * @param string $prefix the prefix added to variables to obtain form names + * @param array $varNames + * @param string $prefix The prefix added to variables to obtain form names * * @return array */ @@ -1092,7 +1092,7 @@ class WebInstaller extends Installer { * @param $text * @param $attribs * @param $parser - * @return String Html for download link + * @return string Html for download link */ public function downloadLinkHook( $text, $attribs, $parser ) { $img = Html::element( 'img', array( -- 2.20.1