From 527e85fa9f090aea00396a120a6d2cc98971e9fe Mon Sep 17 00:00:00 2001 From: Sam Reed Date: Sun, 29 May 2011 14:01:47 +0000 Subject: [PATCH] More documentation in various files --- includes/Linker.php | 38 +++++++- includes/MimeMagic.php | 4 + includes/Preferences.php | 6 +- includes/db/DatabaseOracle.php | 2 +- includes/filerepo/File.php | 47 +++++++--- includes/installer/OracleUpdater.php | 8 ++ includes/parser/Preprocessor_Hash.php | 128 ++++++++++++++++++++++---- 7 files changed, 195 insertions(+), 38 deletions(-) diff --git a/includes/Linker.php b/includes/Linker.php index 2c62389ebb..a5b887a3e9 100644 --- a/includes/Linker.php +++ b/includes/Linker.php @@ -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\n\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
  • ' . $tocnumber . ' ' . diff --git a/includes/MimeMagic.php b/includes/MimeMagic.php index b19c0ba506..6232523866 100644 --- a/includes/MimeMagic.php +++ b/includes/MimeMagic.php @@ -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 diff --git a/includes/Preferences.php b/includes/Preferences.php index b5a2894e0a..a2995ab4f5 100644 --- a/includes/Preferences.php +++ b/includes/Preferences.php @@ -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; diff --git a/includes/db/DatabaseOracle.php b/includes/db/DatabaseOracle.php index 172eaca061..8d86b6f34e 100644 --- a/includes/db/DatabaseOracle.php +++ b/includes/db/DatabaseOracle.php @@ -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 ); diff --git a/includes/filerepo/File.php b/includes/filerepo/File.php index 781f277446..5859cc92ec 100644 --- a/includes/filerepo/File.php +++ b/includes/filerepo/File.php @@ -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' ); } diff --git a/includes/installer/OracleUpdater.php b/includes/installer/OracleUpdater.php index c34369ff19..96aa2a0236 100644 --- a/includes/installer/OracleUpdater.php +++ b/includes/installer/OracleUpdater.php @@ -13,6 +13,14 @@ * @since 1.17 */ class OracleUpdater extends DatabaseUpdater { + + /** + * Handle to the database subclass + * + * @var DatabaseOracle + */ + protected $db; + protected function getCoreUpdateList() { return array( // 1.16 diff --git a/includes/parser/Preprocessor_Hash.php b/includes/parser/Preprocessor_Hash.php index 7f175e58ad..3078e430bf 100644 --- a/includes/parser/Preprocessor_Hash.php +++ b/includes/parser/Preprocessor_Hash.php @@ -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 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 node + * + * @return array */ function splitHeading() { if ( $this->name !== 'h' ) { @@ -1566,6 +1656,8 @@ class PPNode_Hash_Tree implements PPNode { /** * Split a