r89103 MediaWiki - Code Review archive

Repository:MediaWiki
Revision:< r89102‎ | r89103 | r89104 >
Date:14:01, 29 May 2011
Author:reedy
Status:ok
Tags:
Comment:
More documentation in various files
Modified paths:
  • /trunk/phase3/includes/Linker.php (modified) (history)
  • /trunk/phase3/includes/MimeMagic.php (modified) (history)
  • /trunk/phase3/includes/Preferences.php (modified) (history)
  • /trunk/phase3/includes/db/DatabaseOracle.php (modified) (history)
  • /trunk/phase3/includes/filerepo/File.php (modified) (history)
  • /trunk/phase3/includes/installer/OracleUpdater.php (modified) (history)
  • /trunk/phase3/includes/parser/Preprocessor_Hash.php (modified) (history)

Diff [purge]

Index: trunk/phase3/includes/MimeMagic.php
——@@ -424,6 +424,10 @@
425425 /**
426426 * Returns true if the mime type is known to represent an image format
427427 * supported by the PHP GD library.
 428+ *
 429+ * @param $mime string
 430+ *
 431+ * @return bool
428432 */
429433 public function isPHPImageType( $mime ) {
430434 // As defined by imagegetsize and image_type_to_mime
Index: trunk/phase3/includes/parser/Preprocessor_Hash.php
——@@ -39,6 +39,10 @@
4040 return new PPCustomFrame_Hash( $this, $args );
4141 }
4242
 43+ /**
 44+ * @param $values array
 45+ * @return PPNode_Hash_Array
 46+ */
4347 function newPartNodeArray( $values ) {
4448 $list = array();
4549
——@@ -86,7 +90,7 @@
8791 * cache may be implemented at a later date which takes further advantage of these strict
8892 * dependency requirements.
8993 *
90 - * @private
 94+ * @return PPNode_Hash_Tree
9195 */
9296 function preprocessToObj( $text, $flags = 0 ) {
9397 wfProfileIn( __METHOD__ );
——@@ -424,9 +428,7 @@
425429 extract( $stack->getFlags() );
426430 $i += $count;
427431 }
428 - }
429 -
430 - elseif ( $found == 'line-end' ) {
 432+ } elseif ( $found == 'line-end' ) {
431433 $piece = $stack->top;
432434 // A heading must be open, otherwise \n wouldn't have been in the search list
433435 assert( $piece->open == "\n" );
——@@ -488,9 +490,7 @@
489491 // another heading. Infinite loops are avoided because the next iteration MUST
490492 // hit the heading open case above, which unconditionally increments the
491493 // input pointer.
492 - }
493 -
494 - elseif ( $found == 'open' ) {
 494+ } elseif ( $found == 'open' ) {
495495 # count opening brace characters
496496 $count = strspn( $text, $curChar, $i );
497497
——@@ -512,9 +512,7 @@
513513 $accum->addLiteral( str_repeat( $curChar, $count ) );
514514 }
515515 $i += $count;
516 - }
517 -
518 - elseif ( $found == 'close' ) {
 516+ } elseif ( $found == 'close' ) {
519517 $piece = $stack->top;
520518 # lets check if there are enough characters for closing brace
521519 $maxCount = $piece->count;
——@@ -654,16 +652,12 @@
655653 } else {
656654 $accum->addAccum( $element );
657655 }
658 - }
659 -
660 - elseif ( $found == 'pipe' ) {
 656+ } elseif ( $found == 'pipe' ) {
661657 $findEquals = true; // shortcut for getFlags()
662658 $stack->addPart();
663659 $accum =& $stack->getAccum();
664660 ++$i;
665 - }
666 -
667 - elseif ( $found == 'equals' ) {
 661+ } elseif ( $found == 'equals' ) {
668662 $findEquals = false; // shortcut for getFlags()
669663 $accum->addNodeWithText( 'equals', '=' );
670664 $stack->getCurrentPart()->eqpos = $accum->lastNode;
——@@ -724,6 +718,8 @@
725719
726720 /**
727721 * Get the accumulator that would result if the close is not found.
 722+ *
 723+ * @return PPDAccum_Hash
728724 */
729725 function breakSyntax( $openingCount = false ) {
730726 if ( $this->open == "\n" ) {
——@@ -874,6 +870,11 @@
875871 /**
876872 * Create a new child frame
877873 * $args is optionally a multi-root PPNode or array containing the template arguments
 874+ *
 875+ * @param $args PPNode_Hash_Array|array
 876+ * @param $title Title|false
 877+ *
 878+ * @return PPTemplateFrame_Hash
878879 */
879880 function newChild( $args = false, $title = false ) {
880881 $namedArgs = array();
——@@ -904,6 +905,12 @@
905906 return new PPTemplateFrame_Hash( $this->preprocessor, $this, $numberedArgs, $namedArgs, $title );
906907 }
907908
 909+ /**
 910+ * @throws MWException
 911+ * @param $root
 912+ * @param $flags int
 913+ * @return string
 914+ */
908915 function expand( $root, $flags = 0 ) {
909916 static $expansionDepth = 0;
910917 if ( is_string( $root ) ) {
——@@ -1073,6 +1080,11 @@
10741081 return $outStack[0];
10751082 }
10761083
 1084+ /**
 1085+ * @param $sep
 1086+ * @param $flags
 1087+ * @return string
 1088+ */
10771089 function implodeWithFlags( $sep, $flags /*, ... */ ) {
10781090 $args = array_slice( func_get_args(), 2 );
10791091
——@@ -1100,6 +1112,7 @@
11011113 /**
11021114 * Implode with no flags specified
11031115 * This previously called implodeWithFlags but has now been inlined to reduce stack depth
 1116+ * @return string
11041117 */
11051118 function implode( $sep /*, ... */ ) {
11061119 $args = array_slice( func_get_args(), 1 );
——@@ -1128,6 +1141,8 @@
11291142 /**
11301143 * Makes an object that, when expand()ed, will be the same as one obtained
11311144 * with implode()
 1145+ *
 1146+ * @return PPNode_Hash_Array
11321147 */
11331148 function virtualImplode( $sep /*, ... */ ) {
11341149 $args = array_slice( func_get_args(), 1 );
——@@ -1155,6 +1170,8 @@
11561171
11571172 /**
11581173 * Virtual implode with brackets
 1174+ *
 1175+ * @return PPNode_Hash_Array
11591176 */
11601177 function virtualBracketedImplode( $start, $sep, $end /*, ... */ ) {
11611178 $args = array_slice( func_get_args(), 3 );
——@@ -1185,6 +1202,10 @@
11861203 return 'frame{}';
11871204 }
11881205
 1206+ /**
 1207+ * @param $level bool
 1208+ * @return array|bool|String
 1209+ */
11891210 function getPDBK( $level = false ) {
11901211 if ( $level === false ) {
11911212 return $this->title->getPrefixedDBkey();
——@@ -1193,25 +1214,40 @@
11941215 }
11951216 }
11961217
 1218+ /**
 1219+ * @return array
 1220+ */
11971221 function getArguments() {
11981222 return array();
11991223 }
12001224
 1225+ /**
 1226+ * @return array
 1227+ */
12011228 function getNumberedArguments() {
12021229 return array();
12031230 }
12041231
 1232+ /**
 1233+ * @return array
 1234+ */
12051235 function getNamedArguments() {
12061236 return array();
12071237 }
12081238
12091239 /**
12101240 * Returns true if there are no arguments in this frame
 1241+ *
 1242+ * @return bool
12111243 */
12121244 function isEmpty() {
12131245 return true;
12141246 }
12151247
 1248+ /**
 1249+ * @param $name
 1250+ * @return bool
 1251+ */
12161252 function getArgument( $name ) {
12171253 return false;
12181254 }
——@@ -1220,6 +1256,8 @@
12211257 * Returns true if the infinite loop check is OK, false if a loop is detected
12221258 *
12231259 * @param $title Title
 1260+ *
 1261+ * @return bool
12241262 */
12251263 function loopCheck( $title ) {
12261264 return !isset( $this->loopCheckHash[$title->getPrefixedDBkey()] );
——@@ -1227,6 +1265,8 @@
12281266
12291267 /**
12301268 * Return true if the frame is a template frame
 1269+ *
 1270+ * @return bool
12311271 */
12321272 function isTemplate() {
12331273 return false;
——@@ -1326,6 +1366,10 @@
13271367 return $arguments;
13281368 }
13291369
 1370+ /**
 1371+ * @param $index
 1372+ * @return array|bool
 1373+ */
13301374 function getNumberedArgument( $index ) {
13311375 if ( !isset( $this->numberedArgs[$index] ) ) {
13321376 return false;
——@@ -1337,6 +1381,10 @@
13381382 return $this->numberedExpansionCache[$index];
13391383 }
13401384
 1385+ /**
 1386+ * @param $name
 1387+ * @return bool
 1388+ */
13411389 function getNamedArgument( $name ) {
13421390 if ( !isset( $this->namedArgs[$name] ) ) {
13431391 return false;
——@@ -1349,6 +1397,10 @@
13501398 return $this->namedExpansionCache[$name];
13511399 }
13521400
 1401+ /**
 1402+ * @param $name
 1403+ * @return array|bool
 1404+ */
13531405 function getArgument( $name ) {
13541406 $text = $this->getNumberedArgument( $name );
13551407 if ( $text === false ) {
——@@ -1359,6 +1411,8 @@
13601412
13611413 /**
13621414 * Return true if the frame is a template frame
 1415+ *
 1416+ * @return bool
13631417 */
13641418 function isTemplate() {
13651419 return true;
——@@ -1393,10 +1447,17 @@
13941448 return $s;
13951449 }
13961450
 1451+ /**
 1452+ * @return bool
 1453+ */
13971454 function isEmpty() {
13981455 return !count( $this->args );
13991456 }
14001457
 1458+ /**
 1459+ * @param $index
 1460+ * @return bool
 1461+ */
14011462 function getArgument( $index ) {
14021463 if ( !isset( $this->args[$index] ) ) {
14031464 return false;
——@@ -1433,6 +1494,11 @@
14341495 }
14351496 }
14361497
 1498+ /**
 1499+ * @param $name
 1500+ * @param $text
 1501+ * @return PPNode_Hash_Tree
 1502+ */
14371503 static function newWithText( $name, $text ) {
14381504 $obj = new self( $name );
14391505 $obj->addChild( new PPNode_Hash_Text( $text ) );
——@@ -1448,6 +1514,9 @@
14491515 }
14501516 }
14511517
 1518+ /**
 1519+ * @return PPNode_Hash_Array
 1520+ */
14521521 function getChildren() {
14531522 $children = array();
14541523 for ( $child = $this->firstChild; $child; $child = $child->nextSibling ) {
——@@ -1474,9 +1543,24 @@
14751544 return $children;
14761545 }
14771546
1478 - function getLength() { return false; }
1479 - function item( $i ) { return false; }
 1547+ /**
 1548+ * @return bool
 1549+ */
 1550+ function getLength() {
 1551+ return false;
 1552+ }
14801553
 1554+ /**
 1555+ * @param $i
 1556+ * @return bool
 1557+ */
 1558+ function item( $i ) {
 1559+ return false;
 1560+ }
 1561+
 1562+ /**
 1563+ * @return string
 1564+ */
14811565 function getName() {
14821566 return $this->name;
14831567 }
——@@ -1486,6 +1570,8 @@
14871571 * name PPNode name
14881572 * index String index
14891573 * value PPNode value
 1574+ *
 1575+ * @return array
14901576 */
14911577 function splitArg() {
14921578 $bits = array();
——@@ -1517,6 +1603,8 @@
15181604 /**
15191605 * Split an <ext> node into an associative array containing name, attr, inner and close
15201606 * All values in the resulting array are PPNodes. Inner and close are optional.
 1607+ *
 1608+ * @return array
15211609 */
15221610 function splitExt() {
15231611 $bits = array();
——@@ -1542,6 +1630,8 @@
15431631
15441632 /**
15451633 * Split an <h> node
 1634+ *
 1635+ * @return array
15461636 */
15471637 function splitHeading() {
15481638 if ( $this->name !== 'h' ) {
——@@ -1566,6 +1656,8 @@
15671657
15681658 /**
15691659 * Split a <template> or <tplarg> node
 1660+ *
 1661+ * @return array
15701662 */
15711663 function splitTemplate() {
15721664 $parts = array();
Index: trunk/phase3/includes/Linker.php
——@@ -262,6 +262,10 @@
263263 * Returns the array of attributes used when linking to the Title $target
264264 *
265265 * @param $target Title
 266+ * @param $attribs
 267+ * @param $options
 268+ *
 269+ * @return array
266270 */
267271 private static function linkAttribs( $target, $attribs, $options ) {
268272 wfProfileIn( __METHOD__ );
——@@ -834,7 +838,7 @@
835839 * This will make a broken link if $file is false.
836840 *
837841 * @param $title Title object.
838 - * @param $file mixed File object or false
 842+ * @param $file File|false mixed File object or false
839843 * @param $text String: pre-sanitized HTML
840844 * @return String: HTML
841845 *
——@@ -857,12 +861,16 @@
858862 }
859863
860864 /**
861 - * Make a link to a special page given its name and, optionally,
 865+ * Make a link to a special page given its name and, optionally,
862866 * a message key from the link text.
863867 * Usage example: $skin->specialLink( 'recentchanges' )
 868+ *
 869+ * @return bool
864870 */
865871 static function specialLink( $name, $key = '' ) {
866 - if ( $key == '' ) { $key = strtolower( $name ); }
 872+ if ( $key == '' ) {
 873+ $key = strtolower( $name );
 874+ }
867875
868876 return self::linkKnown( SpecialPage::getTitleFor( $name ) , wfMsg( $key ) );
869877 }
——@@ -1103,6 +1111,10 @@
11041112 return $comment;
11051113 }
11061114
 1115+ /**
 1116+ * @param $match
 1117+ * @return string
 1118+ */
11071119 private static function formatAutocommentsCallback( $match ) {
11081120 $title = self::$autocommentTitle;
11091121 $local = self::$autocommentLocal;
——@@ -1149,6 +1161,9 @@
11501162 return $comment;
11511163 }
11521164
 1165+ /**
 1166+ * @var Title
 1167+ */
11531168 static $commentContextTitle;
11541169 static $commentLocal;
11551170
——@@ -1174,6 +1189,10 @@
11751190 return $html;
11761191 }
11771192
 1193+ /**
 1194+ * @param $match
 1195+ * @return mixed
 1196+ */
11781197 protected static function formatLinksInCommentCallback( $match ) {
11791198 global $wgContLang;
11801199
——@@ -1369,6 +1388,10 @@
13701389 return $block;
13711390 }
13721391
 1392+ /**
 1393+ * @param $size
 1394+ * @return string
 1395+ */
13731396 public static function formatRevisionSize( $size ) {
13741397 if ( $size == 0 ) {
13751398 $stxt = wfMsgExt( 'historyempty', 'parsemag' );
——@@ -1383,6 +1406,8 @@
13841407
13851408 /**
13861409 * Add another level to the Table of Contents
 1410+ *
 1411+ * @return string
13871412 */
13881413 static function tocIndent() {
13891414 return "\n<ul>";
——@@ -1390,6 +1415,8 @@
13911416
13921417 /**
13931418 * Finish one or more sublevels on the Table of Contents
 1419+ *
 1420+ * @return string
13941421 */
13951422 static function tocUnindent( $level ) {
13961423 return "</li>\n" . str_repeat( "</ul>\n</li>\n", $level > 0 ? $level : 0 );
——@@ -1397,11 +1424,14 @@
13981425
13991426 /**
14001427 * parameter level defines if we are on an indentation level
 1428+ *
 1429+ * @return string
14011430 */
14021431 static function tocLine( $anchor, $tocline, $tocnumber, $level, $sectionIndex = false ) {
14031432 $classes = "toclevel-$level";
1404 - if ( $sectionIndex !== false )
 1433+ if ( $sectionIndex !== false ) {
14051434 $classes .= " tocsection-$sectionIndex";
 1435+ }
14061436 return "\n<li class=\"$classes\"><a href=\"#" .
14071437 $anchor . '"><span class="tocnumber">' .
14081438 $tocnumber . '</span> <span class="toctext">' .
Index: trunk/phase3/includes/db/DatabaseOracle.php
——@@ -917,7 +917,7 @@
918918 *
919919 * @param $table Array
920920 * @param $field String
921 - * @return ORAField
 921+ * @return ORAField|ORAResult
922922 */
923923 private function fieldInfoMulti( $table, $field ) {
924924 $field = strtoupper( $field );
Index: trunk/phase3/includes/filerepo/File.php
——@@ -287,6 +287,8 @@
288288 *
289289 * STUB
290290 * Overridden by LocalFile, UnregisteredLocalFile
 291+ *
 292+ * @return false|number
291293 */
292294 public function getHeight( $page = 1 ) {
293295 return false;
——@@ -297,8 +299,10 @@
298300 * STUB
299301 *
300302 * @param $type string 'text' or 'id'
 303+ *
 304+ * @return string|int
301305 */
302 - public function getUser( $type='text' ) {
 306+ public function getUser( $type = 'text' ) {
303307 return null;
304308 }
305309
——@@ -317,9 +321,9 @@
318322 }
319323
320324 /**
321 - * Return true if the file is vectorized
 325+ * Return true if the file is vectorized
322326 *
323 - * @retur bool
 327+ * @return bool
324328 */
325329 public function isVectorized() {
326330 $handler = $this->getHandler();
——@@ -335,7 +339,9 @@
336340 * Overridden by LocalFile, UnregisteredLocalFile
337341 * STUB
338342 */
339 - public function getMetadata() { return false; }
 343+ public function getMetadata() {
 344+ return false;
 345+ }
340346
341347 /**
342348 * get versioned metadata
——@@ -362,14 +368,18 @@
363369 * Overridden by LocalFile
364370 * STUB
365371 */
366 - public function getBitDepth() { return 0; }
 372+ public function getBitDepth() {
 373+ return 0;
 374+ }
367375
368376 /**
369377 * Return the size of the image file, in bytes
370378 * Overridden by LocalFile, UnregisteredLocalFile
371379 * STUB
372380 */
373 - public function getSize() { return false; }
 381+ public function getSize() {
 382+ return false;
 383+ }
374384
375385 /**
376386 * Returns the mime type of the file.
——@@ -378,7 +388,9 @@
379389 *
380390 * @return string
381391 */
382 - function getMimeType() { return 'unknown/unknown'; }
 392+ function getMimeType() {
 393+ return 'unknown/unknown';
 394+ }
383395
384396 /**
385397 * Return the type of the media in the file.
——@@ -457,12 +469,20 @@
458470 return $this->isSafeFile;
459471 }
460472
461 - /** Accessor for __get() */
 473+ /**
 474+ * Accessor for __get()
 475+ *
 476+ * @return bool
 477+ */
462478 protected function getIsSafeFile() {
463479 return $this->isSafeFile();
464480 }
465481
466 - /** Uncached accessor */
 482+ /**
 483+ * Uncached accessor
 484+ *
 485+ * @return bool
 486+ */
467487 protected function _getIsSafeFile() {
468488 if ( $this->allowInlineDisplay() ) {
469489 return true;
——@@ -890,7 +910,7 @@
891911 * @return string
892912 */
893913 function getArchivePath( $suffix = false ) {
894 - return $this->repo->getZonePath('public') . '/' . $this->getArchiveRel( $suffix );
 914+ return $this->repo->getZonePath( 'public' ) . '/' . $this->getArchiveRel( $suffix );
895915 }
896916
897917 /**
——@@ -901,7 +921,7 @@
902922 * @return string
903923 */
904924 function getThumbPath( $suffix = false ) {
905 - $path = $this->repo->getZonePath('thumb') . '/' . $this->getRel();
 925+ $path = $this->repo->getZonePath( 'thumb' ) . '/' . $this->getRel();
906926 if ( $suffix !== false ) {
907927 $path .= '/' . $suffix;
908928 }
——@@ -943,7 +963,7 @@
944964 /**
945965 * Get the virtual URL for an archive file or directory
946966 *
947 - * @param $suffix string
 967+ * @param bool|string $suffix
948968 *
949969 * @return string
950970 */
——@@ -994,6 +1014,9 @@
9951015 return $this->repo->isHashed();
9961016 }
9971017
 1018+ /**
 1019+ * @throws MWException
 1020+ */
9981021 function readOnlyError() {
9991022 throw new MWException( get_class($this) . ': write operations are not supported' );
10001023 }
Index: trunk/phase3/includes/installer/OracleUpdater.php
——@@ -13,6 +13,14 @@
1414 * @since 1.17
1515 */
1616 class OracleUpdater extends DatabaseUpdater {
 17+
 18+ /**
 19+ * Handle to the database subclass
 20+ *
 21+ * @var DatabaseOracle
 22+ */
 23+ protected $db;
 24+
1725 protected function getCoreUpdateList() {
1826 return array(
1927 // 1.16
Index: trunk/phase3/includes/Preferences.php
——@@ -1176,9 +1176,9 @@
11771177 }
11781178
11791179 /**
1180 - * @param $signature
1181 - * @param $alldata
1182 - * @return
 1180+ * @param $signature string
 1181+ * @param $alldata array
 1182+ * @return string
11831183 */
11841184 static function cleanSignature( $signature, $alldata ) {
11851185 global $wgParser;

Status & tagging log