From 36cb6833e4ebce9feacd1d4ad53e9464d25d177d Mon Sep 17 00:00:00 2001 From: Sam Reed Date: Sat, 21 May 2011 20:06:57 +0000 Subject: [PATCH] More documentation updates and additions Getting bored of this tonight now I think... --- includes/Article.php | 2 +- includes/ProtectionForm.php | 4 ++- includes/Sanitizer.php | 24 ++++++++++++++ includes/SiteConfiguration.php | 29 ++++++++++++++--- includes/SiteStats.php | 57 ++++++++++++++++++++++++++++++++-- includes/Status.php | 11 +++++++ includes/StreamFile.php | 6 +++- 7 files changed, 124 insertions(+), 9 deletions(-) diff --git a/includes/Article.php b/includes/Article.php index a3f3799aab..1b23a67923 100644 --- a/includes/Article.php +++ b/includes/Article.php @@ -110,7 +110,7 @@ class Article { * * The target will be fetched from the redirect table if possible. * If this page doesn't have an entry there, call insertRedirect() - * @return mixed Title object, or null if this page is not a redirect + * @return Title|mixed object, or null if this page is not a redirect */ public function getRedirectTarget() { if ( !$this->mTitle->isRedirect() ) { diff --git a/includes/ProtectionForm.php b/includes/ProtectionForm.php index 7daab1506a..2e305c3ee0 100644 --- a/includes/ProtectionForm.php +++ b/includes/ProtectionForm.php @@ -147,7 +147,9 @@ class ProtectionForm { /** * Get the expiry time for a given action, by combining the relevant inputs. * - * @return 14-char timestamp or "infinity", or false if the input was invalid + * @param $action string + * + * @return string 14-char timestamp or "infinity", or false if the input was invalid */ function getExpiry( $action ) { if ( $this->mExpirySelection[$action] == 'existing' ) { diff --git a/includes/Sanitizer.php b/includes/Sanitizer.php index dc75a03faf..113a85e112 100644 --- a/includes/Sanitizer.php +++ b/includes/Sanitizer.php @@ -792,6 +792,10 @@ class Sanitizer { return $value; } + /** + * @param $matches array + * @return String + */ static function cssDecodeCallback( $matches ) { if ( $matches[1] !== '' ) { // Line continuation @@ -1093,6 +1097,10 @@ class Sanitizer { Sanitizer::normalizeCharReferences( $text ) ) ); } + /** + * @param $text string + * @return mixed + */ private static function normalizeWhitespace( $text ) { return preg_replace( '/\r\n|[\x20\x0d\x0a\x09]/', @@ -1176,6 +1184,10 @@ class Sanitizer { } } + /** + * @param $codepoint + * @return null|string + */ static function decCharReference( $codepoint ) { $point = intval( $codepoint ); if( Sanitizer::validateCodepoint( $point ) ) { @@ -1185,6 +1197,10 @@ class Sanitizer { } } + /** + * @param $codepoint + * @return null|string + */ static function hexCharReference( $codepoint ) { $point = hexdec( $codepoint ); if( Sanitizer::validateCodepoint( $point ) ) { @@ -1523,6 +1539,10 @@ class Sanitizer { return $out; } + /** + * @param $url string + * @return mixed|string + */ static function cleanUrl( $url ) { # Normalize any HTML entities in input. They will be # re-escaped by makeExternalLink(). @@ -1566,6 +1586,10 @@ class Sanitizer { } } + /** + * @param $matches array + * @return string + */ static function cleanUrlCallback( $matches ) { return urlencode( $matches[0] ); } diff --git a/includes/SiteConfiguration.php b/includes/SiteConfiguration.php index f4a4576a5a..469dda89e1 100644 --- a/includes/SiteConfiguration.php +++ b/includes/SiteConfiguration.php @@ -149,6 +149,11 @@ class SiteConfiguration { /** * Type-safe string replace; won't do replacements on non-strings * private? + * + * @param $from + * @param $to + * @param $in + * @return string */ function doReplace( $from, $to, $in ) { if( is_string( $in ) ) { @@ -204,7 +209,11 @@ class SiteConfiguration { return (bool)($this->get( $setting, $wiki, $suffix, array(), $wikiTags ) ); } - /** Retrieves an array of local databases */ + /** + * Retrieves an array of local databases + * + * @return array + */ function &getLocalDatabases() { return $this->wikis; } @@ -242,6 +251,11 @@ class SiteConfiguration { $this->extractGlobalSetting( $setting, $wiki, $params ); } + /** + * @param $setting string + * @param $wiki string + * @param $params array + */ public function extractGlobalSetting( $setting, $wiki, $params ) { $value = $this->getSetting( $setting, $wiki, $params ); if ( !is_null( $value ) ) { @@ -288,8 +302,9 @@ class SiteConfiguration { 'params' => array(), ); - if( !is_callable( $this->siteParamsCallback ) ) + if( !is_callable( $this->siteParamsCallback ) ) { return $default; + } $ret = call_user_func_array( $this->siteParamsCallback, array( $this, $wiki ) ); # Validate the returned value @@ -339,6 +354,8 @@ class SiteConfiguration { /** * Work out the site and language name from a database name * @param $db + * + * @return array */ public function siteFromDB( $db ) { // Allow override @@ -377,10 +394,14 @@ class SiteConfiguration { * On encountering duplicate keys, merge the two, but ONLY if they're arrays. * PHP's array_merge_recursive() merges ANY duplicate values into arrays, * which is not fun + * + * @param $array1 array + * + * @return array */ static function arrayMerge( $array1/* ... */ ) { $out = $array1; - for( $i=1; $i < func_num_args(); $i++ ) { + for( $i = 1; $i < func_num_args(); $i++ ) { foreach( func_get_arg( $i ) as $key => $value ) { if ( isset($out[$key]) && is_array($out[$key]) && is_array($value) ) { $out[$key] = self::arrayMerge( $out[$key], $value ); @@ -395,7 +416,7 @@ class SiteConfiguration { return $out; } - + public function loadFullData() { if ($this->fullLoadCallback && !$this->fullLoadDone) { call_user_func( $this->fullLoadCallback, $this ); diff --git a/includes/SiteStats.php b/includes/SiteStats.php index 974c62dbc1..d66407b063 100644 --- a/includes/SiteStats.php +++ b/includes/SiteStats.php @@ -13,6 +13,9 @@ class SiteStats { self::load( true ); } + /** + * @param $recache bool + */ static function load( $recache = false ) { if ( self::$loaded && !$recache ) { return; @@ -32,6 +35,9 @@ class SiteStats { self::$loaded = true; } + /** + * @return Bool|ResultWrapper + */ static function loadAndLazyInit() { wfDebug( __METHOD__ . ": reading site_stats from slave\n" ); $row = self::doLoad( wfGetDB( DB_SLAVE ) ); @@ -60,40 +66,65 @@ class SiteStats { return $row; } + /** + * @param $db DatabaseBase + * @return Bool|ResultWrapper + */ static function doLoad( $db ) { return $db->selectRow( 'site_stats', '*', false, __METHOD__ ); } + /** + * @return int + */ static function views() { self::load(); return self::$row->ss_total_views; } + /** + * @return int + */ static function edits() { self::load(); return self::$row->ss_total_edits; } + /** + * @return int + */ static function articles() { self::load(); return self::$row->ss_good_articles; } + /** + * @return int + */ static function pages() { self::load(); return self::$row->ss_total_pages; } + /** + * @return int + */ static function users() { self::load(); return self::$row->ss_users; } + /** + * @return int + */ static function activeUsers() { self::load(); return self::$row->ss_active_users; } + /** + * @return int + */ static function images() { self::load(); return self::$row->ss_images; @@ -124,6 +155,9 @@ class SiteStats { return self::$groupMemberCounts[$group]; } + /** + * @return int + */ static function jobs() { if ( !isset( self::$jobs ) ) { $dbr = wfGetDB( DB_SLAVE ); @@ -136,6 +170,11 @@ class SiteStats { return self::$jobs; } + /** + * @param $ns int + * + * @return int + */ static function pagesInNs( $ns ) { wfProfileIn( __METHOD__ ); if( !isset( self::$pageCount[$ns] ) ) { @@ -151,7 +190,13 @@ class SiteStats { return $pageCount[$ns]; } - /** Is the provided row of site stats sane, or should it be regenerated? */ + /** + * Is the provided row of site stats sane, or should it be regenerated? + * + * @param $row + * + * @return bool + */ private static function isSane( $row ) { if( $row === false @@ -174,7 +219,6 @@ class SiteStats { } } - /** * */ @@ -190,6 +234,11 @@ class SiteStatsUpdate { $this->mUsers = $users; } + /** + * @param $sql + * @param $field + * @param $delta + */ function appendUpdate( &$sql, $field, $delta ) { if ( $delta ) { if ( $sql ) { @@ -225,6 +274,10 @@ class SiteStatsUpdate { } } + /** + * @param $dbw DatabaseBase + * @return bool|mixed + */ public static function cacheUpdate( $dbw ) { global $wgActiveUserDays; $dbr = wfGetDB( DB_SLAVE, array( 'SpecialStatistics', 'vslow' ) ); diff --git a/includes/Status.php b/includes/Status.php index 79179f531d..4fce6e9c32 100644 --- a/includes/Status.php +++ b/includes/Status.php @@ -127,6 +127,10 @@ class Status { $this->cleanCallback = false; } + /** + * @param $params array + * @return array + */ protected function cleanParams( $params ) { if ( !$this->cleanCallback ) { return $params; @@ -138,6 +142,10 @@ class Status { return $cleanParams; } + /** + * @param $item + * @return string + */ protected function getItemXML( $item ) { $params = $this->cleanParams( $item['params'] ); $xml = "<{$item['type']}>\n" . @@ -152,6 +160,7 @@ class Status { /** * Get the error list as XML + * @return string */ function getXML() { $xml = "\n"; @@ -324,6 +333,8 @@ class Status { * destination message, but keep the same parameters as in the original error. * * Return true if the replacement was done, false otherwise. + * + * @return bool */ function replaceMessage( $source, $dest ) { $replaced = false; diff --git a/includes/StreamFile.php b/includes/StreamFile.php index 5f460ee35c..0982a0371f 100644 --- a/includes/StreamFile.php +++ b/includes/StreamFile.php @@ -63,7 +63,11 @@ function wfStreamFile( $fname, $headers = array() ) { readfile( $fname ); } -/** */ +/** + * @param $filename string + * @param $safe bool + * @return null|string + */ function wfGetType( $filename, $safe = true ) { global $wgTrivialMimeDetection; -- 2.20.1