| Index: trunk/phase3/includes/SpecialPage.php |
| — | — | @@ -254,6 +254,9 @@ |
| 255 | 255 | /** |
| 256 | 256 | * Given a special page alias, return the special page name. |
| 257 | 257 | * Returns false if there is no such alias. |
| | 258 | + * |
| | 259 | + * @param $alias String |
| | 260 | + * @return String or false |
| 258 | 261 | */ |
| 259 | 262 | static function resolveAlias( $alias ) { |
| 260 | 263 | global $wgContLang; |
| — | — | @@ -272,6 +275,9 @@ |
| 273 | 276 | * Given a special page name with a possible subpage, return an array |
| 274 | 277 | * where the first element is the special page name and the second is the |
| 275 | 278 | * subpage. |
| | 279 | + * |
| | 280 | + * @param $alias String |
| | 281 | + * @return Array |
| 276 | 282 | */ |
| 277 | 283 | static function resolveAliasWithSubpage( $alias ) { |
| 278 | 284 | $bits = explode( '/', $alias, 2 ); |
| — | — | @@ -289,8 +295,7 @@ |
| 290 | 296 | * method for adding special pages in extensions. It's now suggested that you add |
| 291 | 297 | * an associative record to $wgSpecialPages. This avoids autoloading SpecialPage. |
| 292 | 298 | * |
| 293 | | - * @param SpecialPage $page |
| 294 | | - * @static |
| | 299 | + * @param $page SpecialPage |
| 295 | 300 | */ |
| 296 | 301 | static function addPage( &$page ) { |
| 297 | 302 | if ( !self::$mListInitialised ) { |
| — | — | @@ -302,9 +307,8 @@ |
| 303 | 308 | /** |
| 304 | 309 | * Add a page to a certain display group for Special:SpecialPages |
| 305 | 310 | * |
| 306 | | - * @param mixed $page (SpecialPage or string) |
| 307 | | - * @param string $group |
| 308 | | - * @static |
| | 311 | + * @param $page Mixed: SpecialPage or string |
| | 312 | + * @param $group String |
| 309 | 313 | */ |
| 310 | 314 | static function setGroup( $page, $group ) { |
| 311 | 315 | global $wgSpecialPageGroups; |
| — | — | @@ -315,8 +319,7 @@ |
| 316 | 320 | /** |
| 317 | 321 | * Add a page to a certain display group for Special:SpecialPages |
| 318 | 322 | * |
| 319 | | - * @param SpecialPage $page |
| 320 | | - * @static |
| | 323 | + * @param $page SpecialPage |
| 321 | 324 | */ |
| 322 | 325 | static function getGroup( &$page ) { |
| 323 | 326 | global $wgSpecialPageGroups; |
| — | — | @@ -340,8 +343,6 @@ |
| 341 | 344 | * Remove a special page from the list |
| 342 | 345 | * Formerly used to disable expensive or dangerous special pages. The |
| 343 | 346 | * preferred method is now to add a SpecialPage_initList hook. |
| 344 | | - * |
| 345 | | - * @static |
| 346 | 347 | */ |
| 347 | 348 | static function removePage( $name ) { |
| 348 | 349 | if ( !self::$mListInitialised ) { |
| — | — | @@ -352,8 +353,9 @@ |
| 353 | 354 | |
| 354 | 355 | /** |
| 355 | 356 | * Check if a given name exist as a special page or as a special page alias |
| 356 | | - * @param $name string: name of a special page |
| 357 | | - * @return boolean: true if a special page exists with this name |
| | 357 | + * |
| | 358 | + * @param $name String: name of a special page |
| | 359 | + * @return Boolean: true if a special page exists with this name |
| 358 | 360 | */ |
| 359 | 361 | static function exists( $name ) { |
| 360 | 362 | global $wgContLang; |
| — | — | @@ -376,8 +378,9 @@ |
| 377 | 379 | |
| 378 | 380 | /** |
| 379 | 381 | * Find the object with a given name and return it (or NULL) |
| 380 | | - * @static |
| 381 | | - * @param string $name |
| | 382 | + * |
| | 383 | + * @param $name String |
| | 384 | + * @return SpecialPage object or null if the page doesn't exist |
| 382 | 385 | */ |
| 383 | 386 | static function getPage( $name ) { |
| 384 | 387 | if ( !self::$mListInitialised ) { |
| — | — | @@ -401,6 +404,8 @@ |
| 402 | 405 | /** |
| 403 | 406 | * Get a special page with a given localised name, or NULL if there |
| 404 | 407 | * is no such special page. |
| | 408 | + * |
| | 409 | + * @return SpecialPage object or null if the page doesn't exist |
| 405 | 410 | */ |
| 406 | 411 | static function getPageByAlias( $alias ) { |
| 407 | 412 | $realName = self::resolveAlias( $alias ); |
| — | — | @@ -414,7 +419,8 @@ |
| 415 | 420 | /** |
| 416 | 421 | * Return categorised listable special pages which are available |
| 417 | 422 | * for the current user, and everyone. |
| 418 | | - * @static |
| | 423 | + * |
| | 424 | + * @return Associative array mapping page's name to its SpecialPage object |
| 419 | 425 | */ |
| 420 | 426 | static function getUsablePages() { |
| 421 | 427 | global $wgUser; |
| — | — | @@ -439,7 +445,8 @@ |
| 440 | 446 | |
| 441 | 447 | /** |
| 442 | 448 | * Return categorised listable special pages for all users |
| 443 | | - * @static |
| | 449 | + * |
| | 450 | + * @return Associative array mapping page's name to its SpecialPage object |
| 444 | 451 | */ |
| 445 | 452 | static function getRegularPages() { |
| 446 | 453 | if ( !self::$mListInitialised ) { |
| — | — | @@ -459,7 +466,8 @@ |
| 460 | 467 | /** |
| 461 | 468 | * Return categorised listable special pages which are available |
| 462 | 469 | * for the current user, but not for everyone |
| 463 | | - * @static |
| | 470 | + * |
| | 471 | + * @return Associative array mapping page's name to its SpecialPage object |
| 464 | 472 | */ |
| 465 | 473 | static function getRestrictedPages() { |
| 466 | 474 | global $wgUser; |
| — | — | @@ -566,7 +574,8 @@ |
| 567 | 575 | * Just like executePath() except it returns the HTML instead of outputting it |
| 568 | 576 | * Returns false if there was no such special page, or a title object if it was |
| 569 | 577 | * a redirect. |
| 570 | | - * @static |
| | 578 | + * |
| | 579 | + * @return String: HTML fragment |
| 571 | 580 | */ |
| 572 | 581 | static function capturePath( &$title ) { |
| 573 | 582 | global $wgOut, $wgTitle; |
| — | — | @@ -588,10 +597,10 @@ |
| 589 | 598 | /** |
| 590 | 599 | * Get the local name for a specified canonical name |
| 591 | 600 | * |
| 592 | | - * @param $name |
| 593 | | - * @param mixed $subpage Boolean false, or string |
| | 601 | + * @param $name String |
| | 602 | + * @param $subpage Mixed: boolean false, or string |
| 594 | 603 | * |
| 595 | | - * @return string |
| | 604 | + * @return String |
| 596 | 605 | */ |
| 597 | 606 | static function getLocalNameFor( $name, $subpage = false ) { |
| 598 | 607 | global $wgContLang; |
| — | — | @@ -621,6 +630,8 @@ |
| 622 | 631 | |
| 623 | 632 | /** |
| 624 | 633 | * Get a localised Title object for a specified special page name |
| | 634 | + * |
| | 635 | + * @return Title object |
| 625 | 636 | */ |
| 626 | 637 | static function getTitleFor( $name, $subpage = false ) { |
| 627 | 638 | $name = self::getLocalNameFor( $name, $subpage ); |
| — | — | @@ -633,6 +644,8 @@ |
| 634 | 645 | |
| 635 | 646 | /** |
| 636 | 647 | * Get a localised Title object for a page name with a possibly unvalidated subpage |
| | 648 | + * |
| | 649 | + * @return Title object or null if the page doesn't exist |
| 637 | 650 | */ |
| 638 | 651 | static function getSafeTitleFor( $name, $subpage = false ) { |
| 639 | 652 | $name = self::getLocalNameFor( $name, $subpage ); |
| — | — | @@ -645,6 +658,7 @@ |
| 646 | 659 | |
| 647 | 660 | /** |
| 648 | 661 | * Get a title for a given alias |
| | 662 | + * |
| 649 | 663 | * @return Title or null if there is no such alias |
| 650 | 664 | */ |
| 651 | 665 | static function getTitleForAlias( $alias ) { |
| — | — | @@ -666,11 +680,12 @@ |
| 667 | 681 | * If you override execute(), you can recover the default behaviour with userCanExecute() |
| 668 | 682 | * and displayRestrictionError() |
| 669 | 683 | * |
| 670 | | - * @param string $name Name of the special page, as seen in links and URLs |
| 671 | | - * @param string $restriction User right required, e.g. "block" or "delete" |
| 672 | | - * @param boolean $listed Whether the page is listed in Special:Specialpages |
| 673 | | - * @param string $function Function called by execute(). By default it is constructed from $name |
| 674 | | - * @param string $file File which is included by execute(). It is also constructed from $name by default |
| | 684 | + * @param $name String: name of the special page, as seen in links and URLs |
| | 685 | + * @param $restriction String: user right required, e.g. "block" or "delete" |
| | 686 | + * @param $listed Boolean: whether the page is listed in Special:Specialpages |
| | 687 | + * @param $function Callback: function called by execute(). By default it is constructed from $name |
| | 688 | + * @param $file String: file which is included by execute(). It is also constructed from $name by default |
| | 689 | + * @param $includable Boolean: whether the page can be included in normal pages |
| 675 | 690 | */ |
| 676 | 691 | function SpecialPage( $name = '', $restriction = '', $listed = true, $function = false, $file = 'default', $includable = false ) { |
| 677 | 692 | $this->mName = $name; |
| — | — | @@ -731,7 +746,7 @@ |
| 732 | 747 | * Can be overridden by subclasses with more complicated permissions |
| 733 | 748 | * schemes. |
| 734 | 749 | * |
| 735 | | - * @return bool Should the page be displayed with the restricted-access |
| | 750 | + * @return Boolean: should the page be displayed with the restricted-access |
| 736 | 751 | * pages? |
| 737 | 752 | */ |
| 738 | 753 | public function isRestricted() { |
| — | — | @@ -745,8 +760,8 @@ |
| 746 | 761 | * special page (as defined by $mRestriction). Can be overridden by sub- |
| 747 | 762 | * classes with more complicated permissions schemes. |
| 748 | 763 | * |
| 749 | | - * @param User $user The user to check |
| 750 | | - * @return bool Does the user have permission to view the page? |
| | 764 | + * @param $user User: the user to check |
| | 765 | + * @return Boolean: does the user have permission to view the page? |
| 751 | 766 | */ |
| 752 | 767 | public function userCanExecute( $user ) { |
| 753 | 768 | return $user->isAllowed( $this->mRestriction ); |
| — | — | @@ -800,7 +815,7 @@ |
| 801 | 816 | * May be overriden, i.e. by extensions to stick with the naming conventions |
| 802 | 817 | * for message keys: 'extensionname-xxx' |
| 803 | 818 | * |
| 804 | | - * @param string message key of the summary |
| | 819 | + * @param $summaryMessageKey String: message key of the summary |
| 805 | 820 | */ |
| 806 | 821 | function outputHeader( $summaryMessageKey = '' ) { |
| 807 | 822 | global $wgOut, $wgContLang; |
| — | — | @@ -817,17 +832,24 @@ |
| 818 | 833 | |
| 819 | 834 | } |
| 820 | 835 | |
| 821 | | - # Returns the name that goes in the <h1> in the special page itself, and also the name that |
| 822 | | - # will be listed in Special:Specialpages |
| 823 | | - # |
| 824 | | - # Derived classes can override this, but usually it is easier to keep the default behaviour. |
| 825 | | - # Messages can be added at run-time, see MessageCache.php |
| | 836 | + /** |
| | 837 | + * Returns the name that goes in the \<h1\> in the special page itself, and |
| | 838 | + * also the name that will be listed in Special:Specialpages |
| | 839 | + * |
| | 840 | + * Derived classes can override this, but usually it is easier to keep the |
| | 841 | + * default behaviour. Messages can be added at run-time, see |
| | 842 | + * MessageCache.php. |
| | 843 | + * |
| | 844 | + * @return String |
| | 845 | + */ |
| 826 | 846 | function getDescription() { |
| 827 | 847 | return wfMsg( strtolower( $this->mName ) ); |
| 828 | 848 | } |
| 829 | 849 | |
| 830 | 850 | /** |
| 831 | 851 | * Get a self-referential title object |
| | 852 | + * |
| | 853 | + * @return Title object |
| 832 | 854 | */ |
| 833 | 855 | function getTitle( $subpage = false ) { |
| 834 | 856 | return self::getTitleFor( $this->mName, $subpage ); |
| — | — | @@ -852,7 +874,7 @@ |
| 853 | 875 | * Return part of the request string for a special redirect page |
| 854 | 876 | * This allows passing, e.g. action=history to Special:Mypage, etc. |
| 855 | 877 | * |
| 856 | | - * @return string |
| | 878 | + * @return String |
| 857 | 879 | */ |
| 858 | 880 | function getRedirectQuery() { |
| 859 | 881 | global $wgRequest; |