More documentation updates and additions

Getting bored of this tonight now I think...

diff --git a/includes/Article.php b/includes/Article.php
index a3f3799..1b23a67 100644 (file)
--- 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 7daab15..2e305c3 100644 (file)
--- 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 dc75a03..113a85e 100644 (file)
--- 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 f4a4576..469dda8 100644 (file)
--- 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 974c62d..d66407b 100644 (file)
--- 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 79179f5..4fce6e9 100644 (file)
--- 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 = "<errors>\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 5f460ee..0982a03 100644 (file)
--- 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;