| Index: trunk/phase3/includes/MagicWord.php |
| — | — | @@ -191,6 +191,9 @@ |
| 192 | 192 | |
| 193 | 193 | /** |
| 194 | 194 | * Factory: creates an object representing an ID |
| | 195 | + * |
| | 196 | + * @param $id |
| | 197 | + * |
| 195 | 198 | * @return MagicWord |
| 196 | 199 | */ |
| 197 | 200 | static function &get( $id ) { |
| — | — | @@ -206,6 +209,8 @@ |
| 207 | 210 | |
| 208 | 211 | /** |
| 209 | 212 | * Get an array of parser variable IDs |
| | 213 | + * |
| | 214 | + * @return array |
| 210 | 215 | */ |
| 211 | 216 | static function getVariableIDs() { |
| 212 | 217 | if ( !self::$mVariableIDsInitialised ) { |
| — | — | @@ -230,16 +235,24 @@ |
| 231 | 236 | return self::$mSubstIDs; |
| 232 | 237 | } |
| 233 | 238 | |
| 234 | | - /* Allow external reads of TTL array */ |
| | 239 | + /** |
| | 240 | + * Allow external reads of TTL array |
| | 241 | + * |
| | 242 | + * @return array |
| | 243 | + */ |
| 235 | 244 | static function getCacheTTL($id) { |
| 236 | | - if (array_key_exists($id,self::$mCacheTTLs)) { |
| | 245 | + if ( array_key_exists( $id, self::$mCacheTTLs ) ) { |
| 237 | 246 | return self::$mCacheTTLs[$id]; |
| 238 | 247 | } else { |
| 239 | 248 | return -1; |
| 240 | 249 | } |
| 241 | 250 | } |
| 242 | 251 | |
| 243 | | - /** Get a MagicWordArray of double-underscore entities */ |
| | 252 | + /** |
| | 253 | + * Get a MagicWordArray of double-underscore entities |
| | 254 | + * |
| | 255 | + * @return array |
| | 256 | + */ |
| 244 | 257 | static function getDoubleUnderscoreArray() { |
| 245 | 258 | if ( is_null( self::$mDoubleUnderscoreArray ) ) { |
| 246 | 259 | self::$mDoubleUnderscoreArray = new MagicWordArray( self::$mDoubleUnderscoreIDs ); |
| — | — | @@ -255,7 +268,11 @@ |
| 256 | 269 | self::$mObjects = array(); |
| 257 | 270 | } |
| 258 | 271 | |
| 259 | | - # Initialises this object with an ID |
| | 272 | + /** |
| | 273 | + * Initialises this object with an ID |
| | 274 | + * |
| | 275 | + * @param $id |
| | 276 | + */ |
| 260 | 277 | function load( $id ) { |
| 261 | 278 | global $wgContLang; |
| 262 | 279 | $this->mId = $id; |
| — | — | @@ -295,6 +312,11 @@ |
| 296 | 313 | * A comparison function that returns -1, 0 or 1 depending on whether the |
| 297 | 314 | * first string is longer, the same length or shorter than the second |
| 298 | 315 | * string. |
| | 316 | + * |
| | 317 | + * @param $s1 string |
| | 318 | + * @param $s2 string |
| | 319 | + * |
| | 320 | + * @return int |
| 299 | 321 | */ |
| 300 | 322 | function compareStringLength( $s1, $s2 ) { |
| 301 | 323 | $l1 = strlen( $s1 ); |
| — | — | @@ -310,6 +332,8 @@ |
| 311 | 333 | |
| 312 | 334 | /** |
| 313 | 335 | * Gets a regex representing matching the word |
| | 336 | + * |
| | 337 | + * @return string |
| 314 | 338 | */ |
| 315 | 339 | function getRegex() { |
| 316 | 340 | if ($this->mRegex == '' ) { |
| — | — | @@ -322,6 +346,8 @@ |
| 323 | 347 | * Gets the regexp case modifier to use, i.e. i or nothing, to be used if |
| 324 | 348 | * one is using MagicWord::getBaseRegex(), otherwise it'll be included in |
| 325 | 349 | * the complete expression |
| | 350 | + * |
| | 351 | + * @return string |
| 326 | 352 | */ |
| 327 | 353 | function getRegexCase() { |
| 328 | 354 | if ( $this->mRegex === '' ) |
| — | — | @@ -332,6 +358,8 @@ |
| 333 | 359 | |
| 334 | 360 | /** |
| 335 | 361 | * Gets a regex matching the word, if it is at the string start |
| | 362 | + * |
| | 363 | + * @return string |
| 336 | 364 | */ |
| 337 | 365 | function getRegexStart() { |
| 338 | 366 | if ($this->mRegex == '' ) { |
| — | — | @@ -342,6 +370,8 @@ |
| 343 | 371 | |
| 344 | 372 | /** |
| 345 | 373 | * regex without the slashes and what not |
| | 374 | + * |
| | 375 | + * @return string |
| 346 | 376 | */ |
| 347 | 377 | function getBaseRegex() { |
| 348 | 378 | if ($this->mRegex == '') { |
| — | — | @@ -352,6 +382,9 @@ |
| 353 | 383 | |
| 354 | 384 | /** |
| 355 | 385 | * Returns true if the text contains the word |
| | 386 | + * |
| | 387 | + * @paran $text string |
| | 388 | + * |
| 356 | 389 | * @return bool |
| 357 | 390 | */ |
| 358 | 391 | function match( $text ) { |
| — | — | @@ -360,6 +393,9 @@ |
| 361 | 394 | |
| 362 | 395 | /** |
| 363 | 396 | * Returns true if the text starts with the word |
| | 397 | + * |
| | 398 | + * @param $text string |
| | 399 | + * |
| 364 | 400 | * @return bool |
| 365 | 401 | */ |
| 366 | 402 | function matchStart( $text ) { |
| — | — | @@ -371,6 +407,10 @@ |
| 372 | 408 | * The return code is the matched string, if there's no variable |
| 373 | 409 | * part in the regex and the matched variable part ($1) if there |
| 374 | 410 | * is one. |
| | 411 | + * |
| | 412 | + * @param $text string |
| | 413 | + * |
| | 414 | + * @return string |
| 375 | 415 | */ |
| 376 | 416 | function matchVariableStartToEnd( $text ) { |
| 377 | 417 | $matches = array(); |
| — | — | @@ -385,8 +425,11 @@ |
| 386 | 426 | |
| 387 | 427 | $matches = array_values(array_filter($matches)); |
| 388 | 428 | |
| 389 | | - if ( count($matches) == 1 ) { return $matches[0]; } |
| 390 | | - else { return $matches[1]; } |
| | 429 | + if ( count($matches) == 1 ) { |
| | 430 | + return $matches[0]; |
| | 431 | + } else { |
| | 432 | + return $matches[1]; |
| | 433 | + } |
| 391 | 434 | } |
| 392 | 435 | } |
| 393 | 436 | |
| — | — | @@ -394,6 +437,10 @@ |
| 395 | 438 | /** |
| 396 | 439 | * Returns true if the text matches the word, and alters the |
| 397 | 440 | * input string, removing all instances of the word |
| | 441 | + * |
| | 442 | + * @param $text string |
| | 443 | + * |
| | 444 | + * @return bool |
| 398 | 445 | */ |
| 399 | 446 | function matchAndRemove( &$text ) { |
| 400 | 447 | $this->mFound = false; |
| — | — | @@ -401,6 +448,10 @@ |
| 402 | 449 | return $this->mFound; |
| 403 | 450 | } |
| 404 | 451 | |
| | 452 | + /** |
| | 453 | + * @param $text |
| | 454 | + * @return bool |
| | 455 | + */ |
| 405 | 456 | function matchStartAndRemove( &$text ) { |
| 406 | 457 | $this->mFound = false; |
| 407 | 458 | $text = preg_replace_callback( $this->getRegexStart(), array( &$this, 'pregRemoveAndRecord' ), $text ); |
| — | — | @@ -409,17 +460,24 @@ |
| 410 | 461 | |
| 411 | 462 | /** |
| 412 | 463 | * Used in matchAndRemove() |
| 413 | | - * @private |
| 414 | | - **/ |
| 415 | | - function pregRemoveAndRecord( ) { |
| | 464 | + * |
| | 465 | + * @return string |
| | 466 | + */ |
| | 467 | + function pregRemoveAndRecord() { |
| 416 | 468 | $this->mFound = true; |
| 417 | 469 | return ''; |
| 418 | 470 | } |
| 419 | 471 | |
| 420 | 472 | /** |
| 421 | 473 | * Replaces the word with something else |
| | 474 | + * |
| | 475 | + * @param $replacement |
| | 476 | + * @param $subject |
| | 477 | + * @param $limit int |
| | 478 | + * |
| | 479 | + * @return string |
| 422 | 480 | */ |
| 423 | | - function replace( $replacement, $subject, $limit=-1 ) { |
| | 481 | + function replace( $replacement, $subject, $limit = -1 ) { |
| 424 | 482 | $res = preg_replace( $this->getRegex(), StringUtils::escapeRegexReplacement( $replacement ), $subject, $limit ); |
| 425 | 483 | $this->mModified = !($res === $subject); |
| 426 | 484 | return $res; |
| — | — | @@ -429,6 +487,11 @@ |
| 430 | 488 | * Variable handling: {{SUBST:xxx}} style words |
| 431 | 489 | * Calls back a function to determine what to replace xxx with |
| 432 | 490 | * Input word must contain $1 |
| | 491 | + * |
| | 492 | + * @param $text string |
| | 493 | + * @param $callback |
| | 494 | + * |
| | 495 | + * @return string |
| 433 | 496 | */ |
| 434 | 497 | function substituteCallback( $text, $callback ) { |
| 435 | 498 | $res = preg_replace_callback( $this->getVariableRegex(), $callback, $text ); |
| — | — | @@ -438,6 +501,8 @@ |
| 439 | 502 | |
| 440 | 503 | /** |
| 441 | 504 | * Matches the word, where $1 is a wildcard |
| | 505 | + * |
| | 506 | + * @return string |
| 442 | 507 | */ |
| 443 | 508 | function getVariableRegex() { |
| 444 | 509 | if ( $this->mVariableRegex == '' ) { |
| — | — | @@ -448,6 +513,8 @@ |
| 449 | 514 | |
| 450 | 515 | /** |
| 451 | 516 | * Matches the entire string, where $1 is a wildcard |
| | 517 | + * |
| | 518 | + * @return string |
| 452 | 519 | */ |
| 453 | 520 | function getVariableStartToEndRegex() { |
| 454 | 521 | if ( $this->mVariableStartToEndRegex == '' ) { |
| — | — | @@ -458,11 +525,18 @@ |
| 459 | 526 | |
| 460 | 527 | /** |
| 461 | 528 | * Accesses the synonym list directly |
| | 529 | + * |
| | 530 | + * @param $i int |
| | 531 | + * |
| | 532 | + * @return string |
| 462 | 533 | */ |
| 463 | 534 | function getSynonym( $i ) { |
| 464 | 535 | return $this->mSynonyms[$i]; |
| 465 | 536 | } |
| 466 | 537 | |
| | 538 | + /** |
| | 539 | + * @return array |
| | 540 | + */ |
| 467 | 541 | function getSynonyms() { |
| 468 | 542 | return $this->mSynonyms; |
| 469 | 543 | } |
| — | — | @@ -470,6 +544,8 @@ |
| 471 | 545 | /** |
| 472 | 546 | * Returns true if the last call to replace() or substituteCallback() |
| 473 | 547 | * returned a modified text, otherwise false. |
| | 548 | + * |
| | 549 | + * @return bool |
| 474 | 550 | */ |
| 475 | 551 | function getWasModified(){ |
| 476 | 552 | return $this->mModified; |
| — | — | @@ -480,9 +556,14 @@ |
| 481 | 557 | * This method uses the php feature to do several replacements at the same time, |
| 482 | 558 | * thereby gaining some efficiency. The result is placed in the out variable |
| 483 | 559 | * $result. The return value is true if something was replaced. |
| 484 | | - * @static |
| 485 | 560 | * @todo Should this be static? It doesn't seem to be used at all |
| 486 | | - **/ |
| | 561 | + * |
| | 562 | + * @param $magicarr |
| | 563 | + * @param $subject |
| | 564 | + * @param $result |
| | 565 | + * |
| | 566 | + * @return bool |
| | 567 | + */ |
| 487 | 568 | function replaceMultiple( $magicarr, $subject, &$result ){ |
| 488 | 569 | $search = array(); |
| 489 | 570 | $replace = array(); |
| — | — | @@ -499,6 +580,9 @@ |
| 500 | 581 | /** |
| 501 | 582 | * Adds all the synonyms of this MagicWord to an array, to allow quick |
| 502 | 583 | * lookup in a list of magic words |
| | 584 | + * |
| | 585 | + * @param $array |
| | 586 | + * @param $value |
| 503 | 587 | */ |
| 504 | 588 | function addToArray( &$array, $value ) { |
| 505 | 589 | global $wgContLang; |
| — | — | @@ -507,10 +591,16 @@ |
| 508 | 592 | } |
| 509 | 593 | } |
| 510 | 594 | |
| | 595 | + /** |
| | 596 | + * @return bool |
| | 597 | + */ |
| 511 | 598 | function isCaseSensitive() { |
| 512 | 599 | return $this->mCaseSensitive; |
| 513 | 600 | } |
| 514 | 601 | |
| | 602 | + /** |
| | 603 | + * @return int |
| | 604 | + */ |
| 515 | 605 | function getId() { |
| 516 | 606 | return $this->mId; |
| 517 | 607 | } |
| — | — | @@ -532,6 +622,8 @@ |
| 533 | 623 | |
| 534 | 624 | /** |
| 535 | 625 | * Add a magic word by name |
| | 626 | + * |
| | 627 | + * @param $name string |
| 536 | 628 | */ |
| 537 | 629 | public function add( $name ) { |
| 538 | 630 | $this->names[] = $name; |
| — | — | @@ -540,6 +632,8 @@ |
| 541 | 633 | |
| 542 | 634 | /** |
| 543 | 635 | * Add a number of magic words by name |
| | 636 | + * |
| | 637 | + * $param $names array |
| 544 | 638 | */ |
| 545 | 639 | public function addArray( $names ) { |
| 546 | 640 | $this->names = array_merge( $this->names, array_values( $names ) ); |
| — | — | @@ -608,6 +702,8 @@ |
| 609 | 703 | |
| 610 | 704 | /** |
| 611 | 705 | * Get a regex for matching variables with parameters |
| | 706 | + * |
| | 707 | + * @return string |
| 612 | 708 | */ |
| 613 | 709 | function getVariableRegex() { |
| 614 | 710 | return str_replace( "\\$1", "(.*?)", $this->getRegex() ); |
| — | — | @@ -615,6 +711,8 @@ |
| 616 | 712 | |
| 617 | 713 | /** |
| 618 | 714 | * Get a regex anchored to the start of the string that does not match parameters |
| | 715 | + * |
| | 716 | + * @return string |
| 619 | 717 | */ |
| 620 | 718 | function getRegexStart() { |
| 621 | 719 | $base = $this->getBaseRegex(); |
| — | — | @@ -630,6 +728,8 @@ |
| 631 | 729 | |
| 632 | 730 | /** |
| 633 | 731 | * Get an anchored regex for matching variables with parameters |
| | 732 | + * |
| | 733 | + * @return string |
| 634 | 734 | */ |
| 635 | 735 | function getVariableStartToEndRegex() { |
| 636 | 736 | $base = $this->getBaseRegex(); |
| — | — | @@ -647,6 +747,10 @@ |
| 648 | 748 | * Parse a match array from preg_match |
| 649 | 749 | * Returns array(magic word ID, parameter value) |
| 650 | 750 | * If there is no parameter value, that element will be false. |
| | 751 | + * |
| | 752 | + * @param $m arrray |
| | 753 | + * |
| | 754 | + * @return array |
| 651 | 755 | */ |
| 652 | 756 | function parseMatch( $m ) { |
| 653 | 757 | reset( $m ); |
| — | — | @@ -673,6 +777,10 @@ |
| 674 | 778 | * Returns an array with the magic word name in the first element and the |
| 675 | 779 | * parameter in the second element. |
| 676 | 780 | * Both elements are false if there was no match. |
| | 781 | + * |
| | 782 | + * @param $text string |
| | 783 | + * |
| | 784 | + * @return array |
| 677 | 785 | */ |
| 678 | 786 | public function matchVariableStartToEnd( $text ) { |
| 679 | 787 | $regexes = $this->getVariableStartToEndRegex(); |
| — | — | @@ -690,6 +798,10 @@ |
| 691 | 799 | /** |
| 692 | 800 | * Match some text, without parameter capture |
| 693 | 801 | * Returns the magic word name, or false if there was no capture |
| | 802 | + * |
| | 803 | + * @param $text string |
| | 804 | + * |
| | 805 | + * @return string|false |
| 694 | 806 | */ |
| 695 | 807 | public function matchStartToEnd( $text ) { |
| 696 | 808 | $hash = $this->getHash(); |
| — | — | @@ -707,6 +819,10 @@ |
| 708 | 820 | /** |
| 709 | 821 | * Returns an associative array, ID => param value, for all items that match |
| 710 | 822 | * Removes the matched items from the input string (passed by reference) |
| | 823 | + * |
| | 824 | + * @param $text string |
| | 825 | + * |
| | 826 | + * @return array |
| 711 | 827 | */ |
| 712 | 828 | public function matchAndRemove( &$text ) { |
| 713 | 829 | $found = array(); |
| — | — | @@ -730,6 +846,10 @@ |
| 731 | 847 | * the prefix from $text. |
| 732 | 848 | * Return false if no match found and $text is not modified. |
| 733 | 849 | * Does not match parameters. |
| | 850 | + * |
| | 851 | + * @param $text string |
| | 852 | + * |
| | 853 | + * @return int|false |
| 734 | 854 | */ |
| 735 | 855 | public function matchStartAndRemove( &$text ) { |
| 736 | 856 | $regexes = $this->getRegexStart(); |