From 7c9d61cae3e3af6e7d73d9913a8469f2a38e69dd Mon Sep 17 00:00:00 2001 From: Siebrand Mazeland Date: Sun, 29 Dec 2013 20:20:15 +0100 Subject: [PATCH] Update documentation for SpecialPage and SpecialPageFactory Change-Id: Id601b24bb664a5f15951f72cca34182b72b42d87 --- includes/SpecialPageFactory.php | 52 +++++++-------- includes/specialpage/SpecialPage.php | 97 +++++++++++++++------------- 2 files changed, 75 insertions(+), 74 deletions(-) diff --git a/includes/SpecialPageFactory.php b/includes/SpecialPageFactory.php index 2cd9a3aabd..18b8f0b7fd 100644 --- a/includes/SpecialPageFactory.php +++ b/includes/SpecialPageFactory.php @@ -44,7 +44,6 @@ * @since 1.17 */ class SpecialPageFactory { - /** * List of special page names to the subclass of SpecialPage which handles them. */ @@ -259,8 +258,8 @@ class SpecialPageFactory { * where the first element is the special page name and the second is the * subpage. * - * @param $alias String - * @return Array( String, String|null ), or array( null, null ) if the page is invalid + * @param string $alias + * @return array Array( String, String|null ), or array( null, null ) if the page is invalid */ public static function resolveAlias( $alias ) { global $wgContLang; @@ -286,8 +285,8 @@ class SpecialPageFactory { /** * Add a page to a certain display group for Special:SpecialPages * - * @param $page Mixed: SpecialPage or string - * @param $group String + * @param SpecialPage|string $page + * @param string $group * @deprecated since 1.21 Override SpecialPage::getGroupName */ public static function setGroup( $page, $group ) { @@ -301,8 +300,8 @@ class SpecialPageFactory { /** * Get the group that the special page belongs in on Special:SpecialPage * - * @param $page SpecialPage - * @return String + * @param SpecialPage $page + * @return string * @deprecated since 1.21 Use SpecialPage::getFinalGroupName */ public static function getGroup( &$page ) { @@ -314,8 +313,8 @@ class SpecialPageFactory { /** * Check if a given name exist as a special page or as a special page alias * - * @param string $name name of a special page - * @return Boolean: true if a special page exists with this name + * @param string $name Name of a special page + * @return bool True if a special page exists with this name */ public static function exists( $name ) { list( $title, /*...*/ ) = self::resolveAlias( $name ); @@ -351,9 +350,9 @@ class SpecialPageFactory { * Return categorised listable special pages which are available * for the current user, and everyone. * - * @param $user User object to check permissions, $wgUser will be used - * if not provided - * @return Array( String => Specialpage ) + * @param $user User object to check permissions, $wgUser will be used if + * if not provided + * @return array ( string => Specialpage ) */ public static function getUsablePages( User $user = null ) { $pages = array(); @@ -378,7 +377,7 @@ class SpecialPageFactory { /** * Return categorised listable special pages for all users * - * @return Array( String => Specialpage ) + * @return array ( string => Specialpage ) */ public static function getRegularPages() { $pages = array(); @@ -395,7 +394,7 @@ class SpecialPageFactory { * Return categorised listable special pages which are available * for the current user, but not for everyone * - * @return Array( String => Specialpage ) + * @return array ( string => Specialpage ) */ public static function getRestrictedPages() { global $wgUser; @@ -421,9 +420,9 @@ class SpecialPageFactory { * Returns a title object if the page is redirected, false if there was no such special * page, and true if it was successful. * - * @param $title Title object - * @param $context IContextSource - * @param $including Bool output is being captured for use in {{special:whatever}} + * @param Title $title + * @param IContextSource $context + * @param bool $including Bool output is being captured for use in {{special:whatever}} * * @return bool */ @@ -501,10 +500,9 @@ class SpecialPageFactory { * variables so that the special page will get the context it'd expect on a * normal request, and then restores them to their previous values after. * - * @param $title Title - * @param $context IContextSource - * - * @return String: HTML fragment + * @param Title $title + * @param IContextSource $context + * @return string HTML fragment */ static function capturePath( Title $title, IContextSource $context ) { global $wgOut, $wgTitle, $wgRequest, $wgUser, $wgLang; @@ -539,10 +537,9 @@ class SpecialPageFactory { /** * Get the local name for a specified canonical name * - * @param $name String - * @param $subpage String|Bool - * - * @return String + * @param string $name + * @param string|bool $subpage + * @return string */ static function getLocalNameFor( $name, $subpage = false ) { global $wgContLang; @@ -576,9 +573,8 @@ class SpecialPageFactory { /** * Get a title for a given alias * - * @param $alias String - * - * @return Title or null if there is no such alias + * @param string $alias + * @return Title|null Title or null if there is no such alias */ static function getTitleForAlias( $alias ) { $name = self::resolveAlias( $alias ); diff --git a/includes/specialpage/SpecialPage.php b/includes/specialpage/SpecialPage.php index f50542d4ca..1df52f2f4a 100644 --- a/includes/specialpage/SpecialPage.php +++ b/includes/specialpage/SpecialPage.php @@ -255,11 +255,11 @@ class SpecialPage { /** * Get a localised Title object for a specified special page name * - * @param $name String - * @param string|Bool $subpage subpage string, or false to not use a subpage - * @param string $fragment the link fragment (after the "#") + * @param string $name + * @param string|bool $subpage Subpage string, or false to not use a subpage + * @param string $fragment The link fragment (after the "#") + * @return Title * @throws MWException - * @return Title object */ public static function getTitleFor( $name, $subpage = false, $fragment = '' ) { $name = SpecialPageFactory::getLocalNameFor( $name, $subpage ); @@ -269,9 +269,9 @@ class SpecialPage { /** * Get a localised Title object for a page name with a possibly unvalidated subpage * - * @param $name String - * @param string|Bool $subpage subpage string, or false to not use a subpage - * @return Title object or null if the page doesn't exist + * @param string $name + * @param string|bool $subpage Subpage string, or false to not use a subpage + * @return Title|null Title object or null if the page doesn't exist */ public static function getSafeTitleFor( $name, $subpage = false ) { $name = SpecialPageFactory::getLocalNameFor( $name, $subpage ); @@ -307,10 +307,10 @@ class SpecialPage { * @param string $name Name of the special page, as seen in links and URLs * @param string $restriction User right required, e.g. "block" or "delete" * @param bool $listed Whether the page is listed in Special:Specialpages - * @param Callback|Bool $function Function called by execute(). By default - * it is constructed from $name + * @param callable|bool $function Function called by execute(). By default + * it is constructed from $name * @param string $file File which is included by execute(). It is also - * constructed from $name by default + * constructed from $name by default * @param bool $includable Whether the page can be included in normal pages */ public function __construct( @@ -326,10 +326,10 @@ class SpecialPage { * @param string $name Name of the special page, as seen in links and URLs * @param string $restriction User right required, e.g. "block" or "delete" * @param bool $listed Whether the page is listed in Special:Specialpages - * @param Callback|Bool $function Function called by execute(). By default - * it is constructed from $name + * @param callable|bool $function Function called by execute(). By default + * it is constructed from $name * @param string $file File which is included by execute(). It is also - * constructed from $name by default + * constructed from $name by default * @param bool $includable Whether the page can be included in normal pages */ private function init( $name, $restriction, $listed, $function, $file, $includable ) { @@ -379,7 +379,7 @@ class SpecialPage { /** * Get the name of this Special Page. - * @return String + * @return string */ function getName() { return $this->mName; @@ -387,7 +387,7 @@ class SpecialPage { /** * Get the permission that a user must have to execute this page - * @return String + * @return string */ function getRestriction() { return $this->mRestriction; @@ -397,7 +397,7 @@ class SpecialPage { * Get the file which will be included by SpecialPage::execute() if your extension is * still stuck in the past and hasn't overridden the execute() method. No modern code * should want or need to know this. - * @return String + * @return string * @deprecated since 1.18 */ function getFile() { @@ -409,25 +409,25 @@ class SpecialPage { /** * Whether this special page is listed in Special:SpecialPages * @since r3583 (v1.3) - * @return Bool + * @return bool */ function isListed() { return $this->mListed; } /** * Set whether this page is listed in Special:Specialpages, at run-time - * @since r3583 (v1.3) - * @param $listed Bool - * @return Bool + * @since 1.3 + * @param bool $listed + * @return bool */ function setListed( $listed ) { return wfSetVar( $this->mListed, $listed ); } /** * Get or set whether this special page is listed in Special:SpecialPages - * @since r11308 (v1.6) - * @param $x Bool - * @return Bool + * @since 1.6 + * @param bool $x + * @return bool */ function listed( $x = null ) { return wfSetVar( $this->mListed, $x ); @@ -435,7 +435,7 @@ class SpecialPage { /** * Whether it's allowed to transclude the special page via {{Special:Foo/params}} - * @return Bool + * @return bool */ public function isIncludable() { return $this->mIncludable; @@ -503,8 +503,8 @@ class SpecialPage { /** * Whether the special page is being evaluated via transclusion - * @param $x Bool - * @return Bool + * @param bool $x + * @return bool */ function including( $x = null ) { return wfSetVar( $this->mIncluding, $x ); @@ -512,6 +512,7 @@ class SpecialPage { /** * Get the localised name of the special page + * @return string */ function getLocalName() { if ( !isset( $this->mLocalName ) ) { @@ -526,7 +527,7 @@ class SpecialPage { * (and still overridden) by QueryPage and subclasses, moved here so that * Special:SpecialPages can safely call it for all special pages. * - * @return Boolean + * @return bool */ public function isExpensive() { return false; @@ -538,7 +539,7 @@ class SpecialPage { * Used by QueryPage and subclasses, moved here so that * Special:SpecialPages can safely call it for all special pages. * - * @return Boolean + * @return bool * @since 1.21 */ public function isCached() { @@ -549,7 +550,7 @@ class SpecialPage { * Can be overridden by subclasses with more complicated permissions * schemes. * - * @return Boolean: should the page be displayed with the restricted-access + * @return bool Should the page be displayed with the restricted-access * pages? */ public function isRestricted() { @@ -562,8 +563,8 @@ class SpecialPage { * special page (as defined by $mRestriction). Can be overridden by sub- * classes with more complicated permissions schemes. * - * @param $user User: the user to check - * @return Boolean: does the user have permission to view the page? + * @param User $user The user to check + * @return bool Does the user have permission to view the page? */ public function userCanExecute( User $user ) { return $user->isAllowed( $this->mRestriction ); @@ -571,6 +572,7 @@ class SpecialPage { /** * Output an error message telling the user what access level they have to have + * @throws PermissionsError */ function displayRestrictionError() { throw new PermissionsError( $this->mRestriction ); @@ -580,6 +582,8 @@ class SpecialPage { * Checks if userCanExecute, and if not throws a PermissionsError * * @since 1.19 + * @return void + * @throws PermissionsError */ public function checkPermissions() { if ( !$this->userCanExecute( $this->getUser() ) ) { @@ -591,6 +595,7 @@ class SpecialPage { * If the wiki is currently in readonly mode, throws a ReadOnlyError * * @since 1.19 + * @return void * @throws ReadOnlyError */ public function checkReadOnly() { @@ -657,7 +662,7 @@ class SpecialPage { * * @since 1.20 * - * @param $subPage string|null + * @param string|null $subPage */ final public function run( $subPage ) { /** @@ -665,8 +670,8 @@ class SpecialPage { * * @since 1.20 * - * @param $special SpecialPage - * @param $subPage string|null + * @param SpecialPage $this + * @param string|null $subPage */ wfRunHooks( 'SpecialPageBeforeExecute', array( $this, $subPage ) ); @@ -679,8 +684,8 @@ class SpecialPage { * * @since 1.20 * - * @param $special SpecialPage - * @param $subPage string|null + * @param SpecialPage $this + * @param string|null $subPage */ wfRunHooks( 'SpecialPageAfterExecute', array( $this, $subPage ) ); } @@ -690,7 +695,7 @@ class SpecialPage { * * @since 1.20 * - * @param $subPage string|null + * @param string|null $subPage */ protected function beforeExecute( $subPage ) { // No-op @@ -701,7 +706,7 @@ class SpecialPage { * * @since 1.20 * - * @param $subPage string|null + * @param string|null $subPage */ protected function afterExecute( $subPage ) { // No-op @@ -713,7 +718,7 @@ class SpecialPage { * * This must be overridden by subclasses; it will be made abstract in a future version * - * @param $subPage string|null + * @param string|null $subPage */ public function execute( $subPage ) { $this->setHeaders(); @@ -734,7 +739,7 @@ class SpecialPage { * May be overridden, i.e. by extensions to stick with the naming conventions * for message keys: 'extensionname-xxx' * - * @param string $summaryMessageKey message key of the summary + * @param string $summaryMessageKey Message key of the summary */ function outputHeader( $summaryMessageKey = '' ) { global $wgContLang; @@ -767,8 +772,8 @@ class SpecialPage { /** * Get a self-referential title object * - * @param $subpage String|Bool - * @return Title object + * @param string|bool $subpage + * @return Title * @deprecated in 1.23, use SpecialPage::getPageTitle */ function getTitle( $subpage = false ) { @@ -779,8 +784,8 @@ class SpecialPage { /** * Get a self-referential title object * - * @param $subpage String|Bool - * @return Title object + * @param string|bool $subpage + * @return Title * @since 1.23 */ function getPageTitle( $subpage = false ) { @@ -790,7 +795,7 @@ class SpecialPage { /** * Sets the context this SpecialPage is executed in * - * @param $context IContextSource + * @param IContextSource $context * @since 1.18 */ public function setContext( $context ) { @@ -909,7 +914,7 @@ class SpecialPage { /** * Adds RSS/atom links * - * @param $params array + * @param array $params */ protected function addFeedLinks( $params ) { global $wgFeedClasses; -- 2.20.1