More documentation in various files
authorSam Reed <reedy@users.mediawiki.org>
Sun, 29 May 2011 14:01:47 +0000 (14:01 +0000)
committerSam Reed <reedy@users.mediawiki.org>
Sun, 29 May 2011 14:01:47 +0000 (14:01 +0000)
includes/Linker.php
includes/MimeMagic.php
includes/Preferences.php
includes/db/DatabaseOracle.php
includes/filerepo/File.php
includes/installer/OracleUpdater.php
includes/parser/Preprocessor_Hash.php

index 2c62389..a5b887a 100644 (file)
@@ -262,6 +262,10 @@ class Linker {
         * Returns the array of attributes used when linking to the Title $target
         *
         * @param $target Title
+        * @param $attribs
+        * @param $options
+        * 
+        * @return array
         */
        private static function linkAttribs( $target, $attribs, $options ) {
                wfProfileIn( __METHOD__ );
@@ -834,7 +838,7 @@ class Linker {
         * This will make a broken link if $file is false.
         *
         * @param $title Title object.
-        * @param $file mixed File object or false
+        * @param $file File|false mixed File object or false
         * @param $text String: pre-sanitized HTML
         * @return String: HTML
         *
@@ -857,12 +861,16 @@ class Linker {
        }
 
        /**
-        *  Make a link to a special page given its name and, optionally,
+        * Make a link to a special page given its name and, optionally,
         * a message key from the link text.
         * Usage example: $skin->specialLink( 'recentchanges' )
+        *
+        * @return bool
         */
        static function specialLink( $name, $key = '' ) {
-               if ( $key == '' ) { $key = strtolower( $name ); }
+               if ( $key == '' ) {
+                       $key = strtolower( $name );
+               }
 
                return self::linkKnown( SpecialPage::getTitleFor( $name ) , wfMsg( $key ) );
        }
@@ -1103,6 +1111,10 @@ class Linker {
                return $comment;
        }
 
+       /**
+        * @param $match
+        * @return string
+        */
        private static function formatAutocommentsCallback( $match ) {
                $title = self::$autocommentTitle;
                $local = self::$autocommentLocal;
@@ -1149,6 +1161,9 @@ class Linker {
                return $comment;
        }
 
+       /**
+        * @var Title
+        */
        static $commentContextTitle;
        static $commentLocal;
 
@@ -1174,6 +1189,10 @@ class Linker {
                return $html;
        }
 
+       /**
+        * @param $match
+        * @return mixed
+        */
        protected static function formatLinksInCommentCallback( $match ) {
                global $wgContLang;
 
@@ -1369,6 +1388,10 @@ class Linker {
                return $block;
        }
 
+       /**
+        * @param $size
+        * @return string
+        */
        public static function formatRevisionSize( $size ) {
                if ( $size == 0 ) {
                        $stxt = wfMsgExt( 'historyempty', 'parsemag' );
@@ -1383,6 +1406,8 @@ class Linker {
 
        /**
         * Add another level to the Table of Contents
+        *
+        * @return string
         */
        static function tocIndent() {
                return "\n<ul>";
@@ -1390,6 +1415,8 @@ class Linker {
 
        /**
         * Finish one or more sublevels on the Table of Contents
+        *
+        * @return string
         */
        static function tocUnindent( $level ) {
                return "</li>\n" . str_repeat( "</ul>\n</li>\n", $level > 0 ? $level : 0 );
@@ -1397,11 +1424,14 @@ class Linker {
 
        /**
         * parameter level defines if we are on an indentation level
+        *
+        * @return string
         */
        static function tocLine( $anchor, $tocline, $tocnumber, $level, $sectionIndex = false ) {
                $classes = "toclevel-$level";
-               if ( $sectionIndex !== false )
+               if ( $sectionIndex !== false ) {
                        $classes .= " tocsection-$sectionIndex";
+               }
                return "\n<li class=\"$classes\"><a href=\"#" .
                        $anchor . '"><span class="tocnumber">' .
                        $tocnumber . '</span> <span class="toctext">' .
index b19c0ba..6232523 100644 (file)
@@ -424,6 +424,10 @@ class MimeMagic {
        /** 
         * Returns true if the mime type is known to represent an image format 
         * supported by the PHP GD library.
+        *
+        * @param $mime string
+        * 
+        * @return bool
         */
        public function isPHPImageType( $mime ) {
                // As defined by imagegetsize and image_type_to_mime
index b5a2894..a2995ab 100644 (file)
@@ -1176,9 +1176,9 @@ class Preferences {
        }
 
        /**
-        * @param $signature
-        * @param $alldata
-        * @return
+        * @param $signature string
+        * @param $alldata array
+        * @return string
         */
        static function cleanSignature( $signature, $alldata ) {
                global $wgParser;
index 172eaca..8d86b6f 100644 (file)
@@ -917,7 +917,7 @@ class DatabaseOracle extends DatabaseBase {
         *
         * @param $table Array
         * @param $field String
-        * @return ORAField
+        * @return ORAField|ORAResult
         */
        private function fieldInfoMulti( $table, $field ) {
                $field = strtoupper( $field );
index 781f277..5859cc9 100644 (file)
@@ -287,6 +287,8 @@ abstract class File {
         *
         * STUB
         * Overridden by LocalFile, UnregisteredLocalFile
+        *
+        * @return false|number
         */
        public function getHeight( $page = 1 ) {
                return false;
@@ -297,8 +299,10 @@ abstract class File {
         * STUB
         *
         * @param $type string 'text' or 'id'
+        *
+        * @return string|int
         */
-       public function getUser( $type='text' ) {
+       public function getUser( $type = 'text' ) {
                return null;
        }
 
@@ -317,9 +321,9 @@ abstract class File {
        }
 
        /**
-        *  Return true if the file is vectorized
+        * Return true if the file is vectorized
         *
-        * @retur bool
+        * @return bool
         */
        public function isVectorized() {
                $handler = $this->getHandler();
@@ -335,7 +339,9 @@ abstract class File {
         * Overridden by LocalFile, UnregisteredLocalFile
         * STUB
         */
-       public function getMetadata() { return false; }
+       public function getMetadata() {
+               return false;
+       }
 
        /**
        * get versioned metadata
@@ -362,14 +368,18 @@ abstract class File {
         * Overridden by LocalFile
         * STUB
         */
-       public function getBitDepth() { return 0; }
+       public function getBitDepth() {
+               return 0;
+       }
 
        /**
         * Return the size of the image file, in bytes
         * Overridden by LocalFile, UnregisteredLocalFile
         * STUB
         */
-       public function getSize() { return false; }
+       public function getSize() {
+               return false;
+       }
 
        /**
         * Returns the mime type of the file.
@@ -378,7 +388,9 @@ abstract class File {
         *
         * @return string
         */
-       function getMimeType() { return 'unknown/unknown'; }
+       function getMimeType() {
+               return 'unknown/unknown';
+       }
 
        /**
         * Return the type of the media in the file.
@@ -457,12 +469,20 @@ abstract class File {
                return $this->isSafeFile;
        }
 
-       /** Accessor for __get() */
+       /**
+        * Accessor for __get()
+        * 
+        * @return bool
+        */
        protected function getIsSafeFile() {
                return $this->isSafeFile();
        }
 
-       /** Uncached accessor */
+       /**
+        * Uncached accessor
+        *
+        * @return bool
+        */
        protected function _getIsSafeFile() {
                if ( $this->allowInlineDisplay() ) {
                        return true;
@@ -890,7 +910,7 @@ abstract class File {
         * @return string
         */
        function getArchivePath( $suffix = false ) {
-               return $this->repo->getZonePath('public') . '/' . $this->getArchiveRel( $suffix );
+               return $this->repo->getZonePath( 'public' ) . '/' . $this->getArchiveRel( $suffix );
        }
 
        /**
@@ -901,7 +921,7 @@ abstract class File {
         * @return string
         */
        function getThumbPath( $suffix = false ) {
-               $path = $this->repo->getZonePath('thumb') . '/' . $this->getRel();
+               $path = $this->repo->getZonePath( 'thumb' ) . '/' . $this->getRel();
                if ( $suffix !== false ) {
                        $path .= '/' . $suffix;
                }
@@ -943,7 +963,7 @@ abstract class File {
        /**
         * Get the virtual URL for an archive file or directory
         *
-        * @param $suffix string
+        * @param bool|string $suffix
         *
         * @return string
         */
@@ -994,6 +1014,9 @@ abstract class File {
                return $this->repo->isHashed();
        }
 
+       /**
+        * @throws MWException
+        */
        function readOnlyError() {
                throw new MWException( get_class($this) . ': write operations are not supported' );
        }
index c34369f..96aa2a0 100644 (file)
  * @since 1.17
  */
 class OracleUpdater extends DatabaseUpdater {
+
+       /**
+        * Handle to the database subclass
+        *
+        * @var DatabaseOracle
+        */
+       protected $db;
+
        protected function getCoreUpdateList() {
                return array(
                        // 1.16
index 7f175e5..3078e43 100644 (file)
@@ -39,6 +39,10 @@ class Preprocessor_Hash implements Preprocessor {
                return new PPCustomFrame_Hash( $this, $args );
        }
 
+       /**
+        * @param $values array
+        * @return PPNode_Hash_Array
+        */
        function newPartNodeArray( $values ) {
                $list = array();
 
@@ -86,7 +90,7 @@ class Preprocessor_Hash implements Preprocessor {
         * cache may be implemented at a later date which takes further advantage of these strict
         * dependency requirements.
         *
-        * @private
+        * @return PPNode_Hash_Tree
         */
        function preprocessToObj( $text, $flags = 0 ) {
                wfProfileIn( __METHOD__ );
@@ -424,9 +428,7 @@ class Preprocessor_Hash implements Preprocessor {
                                        extract( $stack->getFlags() );
                                        $i += $count;
                                }
-                       }
-
-                       elseif ( $found == 'line-end' ) {
+                       } elseif ( $found == 'line-end' ) {
                                $piece = $stack->top;
                                // A heading must be open, otherwise \n wouldn't have been in the search list
                                assert( $piece->open == "\n" );
@@ -488,9 +490,7 @@ class Preprocessor_Hash implements Preprocessor {
                                // another heading. Infinite loops are avoided because the next iteration MUST
                                // hit the heading open case above, which unconditionally increments the
                                // input pointer.
-                       }
-
-                       elseif ( $found == 'open' ) {
+                       } elseif ( $found == 'open' ) {
                                # count opening brace characters
                                $count = strspn( $text, $curChar, $i );
 
@@ -512,9 +512,7 @@ class Preprocessor_Hash implements Preprocessor {
                                        $accum->addLiteral( str_repeat( $curChar, $count ) );
                                }
                                $i += $count;
-                       }
-
-                       elseif ( $found == 'close' ) {
+                       } elseif ( $found == 'close' ) {
                                $piece = $stack->top;
                                # lets check if there are enough characters for closing brace
                                $maxCount = $piece->count;
@@ -654,16 +652,12 @@ class Preprocessor_Hash implements Preprocessor {
                                } else {
                                        $accum->addAccum( $element );
                                }
-                       }
-
-                       elseif ( $found == 'pipe' ) {
+                       } elseif ( $found == 'pipe' ) {
                                $findEquals = true; // shortcut for getFlags()
                                $stack->addPart();
                                $accum =& $stack->getAccum();
                                ++$i;
-                       }
-
-                       elseif ( $found == 'equals' ) {
+                       } elseif ( $found == 'equals' ) {
                                $findEquals = false; // shortcut for getFlags()
                                $accum->addNodeWithText( 'equals', '=' );
                                $stack->getCurrentPart()->eqpos = $accum->lastNode;
@@ -724,6 +718,8 @@ class PPDStackElement_Hash extends PPDStackElement {
 
        /**
         * Get the accumulator that would result if the close is not found.
+        *
+        * @return PPDAccum_Hash
         */
        function breakSyntax( $openingCount = false ) {
                if ( $this->open == "\n" ) {
@@ -874,6 +870,11 @@ class PPFrame_Hash implements PPFrame {
        /**
         * Create a new child frame
         * $args is optionally a multi-root PPNode or array containing the template arguments
+        *
+        * @param $args PPNode_Hash_Array|array
+        * @param $title Title|false
+        *
+        * @return PPTemplateFrame_Hash
         */
        function newChild( $args = false, $title = false ) {
                $namedArgs = array();
@@ -904,6 +905,12 @@ class PPFrame_Hash implements PPFrame {
                return new PPTemplateFrame_Hash( $this->preprocessor, $this, $numberedArgs, $namedArgs, $title );
        }
 
+       /**
+        * @throws MWException
+        * @param $root
+        * @param $flags int
+        * @return string
+        */
        function expand( $root, $flags = 0 ) {
                static $expansionDepth = 0;
                if ( is_string( $root ) ) {
@@ -1073,6 +1080,11 @@ class PPFrame_Hash implements PPFrame {
                return $outStack[0];
        }
 
+       /**
+        * @param $sep
+        * @param $flags
+        * @return string
+        */
        function implodeWithFlags( $sep, $flags /*, ... */ ) {
                $args = array_slice( func_get_args(), 2 );
 
@@ -1100,6 +1112,7 @@ class PPFrame_Hash implements PPFrame {
        /**
         * Implode with no flags specified
         * This previously called implodeWithFlags but has now been inlined to reduce stack depth
+        * @return string
         */
        function implode( $sep /*, ... */ ) {
                $args = array_slice( func_get_args(), 1 );
@@ -1128,6 +1141,8 @@ class PPFrame_Hash implements PPFrame {
        /**
         * Makes an object that, when expand()ed, will be the same as one obtained
         * with implode()
+        *
+        * @return PPNode_Hash_Array
         */
        function virtualImplode( $sep /*, ... */ ) {
                $args = array_slice( func_get_args(), 1 );
@@ -1155,6 +1170,8 @@ class PPFrame_Hash implements PPFrame {
 
        /**
         * Virtual implode with brackets
+        *
+        * @return PPNode_Hash_Array
         */
        function virtualBracketedImplode( $start, $sep, $end /*, ... */ ) {
                $args = array_slice( func_get_args(), 3 );
@@ -1185,6 +1202,10 @@ class PPFrame_Hash implements PPFrame {
                return 'frame{}';
        }
 
+       /**
+        * @param $level bool
+        * @return array|bool|String
+        */
        function getPDBK( $level = false ) {
                if ( $level === false ) {
                        return $this->title->getPrefixedDBkey();
@@ -1193,25 +1214,40 @@ class PPFrame_Hash implements PPFrame {
                }
        }
 
+       /**
+        * @return array
+        */
        function getArguments() {
                return array();
        }
 
+       /**
+        * @return array
+        */
        function getNumberedArguments() {
                return array();
        }
 
+       /**
+        * @return array
+        */
        function getNamedArguments() {
                return array();
        }
 
        /**
         * Returns true if there are no arguments in this frame
+        *
+        * @return bool
         */
        function isEmpty() {
                return true;
        }
 
+       /**
+        * @param $name
+        * @return bool
+        */
        function getArgument( $name ) {
                return false;
        }
@@ -1220,6 +1256,8 @@ class PPFrame_Hash implements PPFrame {
         * Returns true if the infinite loop check is OK, false if a loop is detected
         *
         * @param $title Title
+        *
+        * @return bool
         */
        function loopCheck( $title ) {
                return !isset( $this->loopCheckHash[$title->getPrefixedDBkey()] );
@@ -1227,6 +1265,8 @@ class PPFrame_Hash implements PPFrame {
 
        /**
         * Return true if the frame is a template frame
+        *
+        * @return bool
         */
        function isTemplate() {
                return false;
@@ -1326,6 +1366,10 @@ class PPTemplateFrame_Hash extends PPFrame_Hash {
                return $arguments;
        }
 
+       /**
+        * @param $index
+        * @return array|bool
+        */
        function getNumberedArgument( $index ) {
                if ( !isset( $this->numberedArgs[$index] ) ) {
                        return false;
@@ -1337,6 +1381,10 @@ class PPTemplateFrame_Hash extends PPFrame_Hash {
                return $this->numberedExpansionCache[$index];
        }
 
+       /**
+        * @param $name
+        * @return bool
+        */
        function getNamedArgument( $name ) {
                if ( !isset( $this->namedArgs[$name] ) ) {
                        return false;
@@ -1349,6 +1397,10 @@ class PPTemplateFrame_Hash extends PPFrame_Hash {
                return $this->namedExpansionCache[$name];
        }
 
+       /**
+        * @param $name
+        * @return array|bool
+        */
        function getArgument( $name ) {
                $text = $this->getNumberedArgument( $name );
                if ( $text === false ) {
@@ -1359,6 +1411,8 @@ class PPTemplateFrame_Hash extends PPFrame_Hash {
 
        /**
         * Return true if the frame is a template frame
+        *
+        * @return bool
         */
        function isTemplate() {
                return true;
@@ -1393,10 +1447,17 @@ class PPCustomFrame_Hash extends PPFrame_Hash {
                return $s;
        }
 
+       /**
+        * @return bool
+        */
        function isEmpty() {
                return !count( $this->args );
        }
 
+       /**
+        * @param $index
+        * @return bool
+        */
        function getArgument( $index ) {
                if ( !isset( $this->args[$index] ) ) {
                        return false;
@@ -1433,6 +1494,11 @@ class PPNode_Hash_Tree implements PPNode {
                }
        }
 
+       /**
+        * @param $name
+        * @param $text
+        * @return PPNode_Hash_Tree
+        */
        static function newWithText( $name, $text ) {
                $obj = new self( $name );
                $obj->addChild( new PPNode_Hash_Text( $text ) );
@@ -1448,6 +1514,9 @@ class PPNode_Hash_Tree implements PPNode {
                }
        }
 
+       /**
+        * @return PPNode_Hash_Array
+        */
        function getChildren() {
                $children = array();
                for ( $child = $this->firstChild; $child; $child = $child->nextSibling ) {
@@ -1474,9 +1543,24 @@ class PPNode_Hash_Tree implements PPNode {
                return $children;
        }
 
-       function getLength() { return false; }
-       function item( $i ) { return false; }
+       /**
+        * @return bool
+        */
+       function getLength() {
+               return false;
+       }
+
+       /**
+        * @param  $i
+        * @return bool
+        */
+       function item( $i ) {
+               return false;
+       }
 
+       /**
+        * @return string
+        */
        function getName() {
                return $this->name;
        }
@@ -1486,6 +1570,8 @@ class PPNode_Hash_Tree implements PPNode {
         *    name          PPNode name
         *    index         String index
         *    value         PPNode value
+        *
+        * @return array
         */
        function splitArg() {
                $bits = array();
@@ -1517,6 +1603,8 @@ class PPNode_Hash_Tree implements PPNode {
        /**
         * Split an <ext> node into an associative array containing name, attr, inner and close
         * All values in the resulting array are PPNodes. Inner and close are optional.
+        *
+        * @return array
         */
        function splitExt() {
                $bits = array();
@@ -1542,6 +1630,8 @@ class PPNode_Hash_Tree implements PPNode {
 
        /**
         * Split an <h> node
+        *
+        * @return array
         */
        function splitHeading() {
                if ( $this->name !== 'h' ) {
@@ -1566,6 +1656,8 @@ class PPNode_Hash_Tree implements PPNode {
 
        /**
         * Split a <template> or <tplarg> node
+        *
+        * @return array
         */
        function splitTemplate() {
                $parts = array();