/**
* Create a new Title from a prefixed DB key
+ *
* @param $key \type{\string} The database key, which has underscores
* instead of spaces, possibly including namespace and
* interwiki prefixes
*
* Create a new Title from URL-encoded text. Ensures that
* the given title's length does not exceed the maximum.
+ *
* @param $url \type{\string} the title, as might be taken from a URL
* @return \type{Title} the new object, or NULL on an error
*/
/**
* Make an array of titles from an array of IDs
+ *
* @param $ids \type{\arrayof{\int}} Array of IDs
* @return \type{\arrayof{Title}} Array of Titles
*/
/**
* Make a Title object from a DB row
+ *
* @param $row \type{Row} (needs at least page_title,page_namespace)
* @return \type{Title} corresponding Title
*/
/**
* Create a new Title for the Main Page
+ *
* @return \type{Title} the new object
*/
public static function newMainPage() {
/**
* Get the prefixed DB key associated with an ID
+ *
* @param $id \type{\int} the page_id of the article
* @return \type{Title} an object representing the article, or NULL
* if no such article was found
/**
* Get a regex character class describing the legal characters in a link
+ *
* @return \type{\string} the list of characters, not delimited
*/
public static function legalChars() {
/**
* Make a prefixed DB key from a DB key and a namespace index
+ *
* @param $ns \type{\int} numerical representation of the namespace
* @param $title \type{\string} the DB key form the title
* @param $fragment \type{\string} The link fragment (after the "#")
* Escape a text fragment, say from a link, for a URL
*
* @param $fragment string containing a URL or link fragment (after the "#")
- * @return string escaped string
+ * @return String: escaped string
*/
static function escapeFragmentForURL( $fragment ) {
# Note that we don't urlencode the fragment. urlencoded Unicode
/** Simple accessors */
/**
* Get the text form (spaces not underscores) of the main part
+ *
* @return \type{\string} Main part of the title
*/
public function getText() { return $this->mTextform; }
+
/**
* Get the URL-encoded form of the main part
+ *
* @return \type{\string} Main part of the title, URL-encoded
*/
public function getPartialURL() { return $this->mUrlform; }
+
/**
* Get the main part with underscores
+ *
* @return \type{\string} Main part of the title, with underscores
*/
public function getDBkey() { return $this->mDbkeyform; }
+
/**
* Get the namespace index, i.e.\ one of the NS_xxxx constants.
+ *
* @return \type{\int} Namespace index
*/
public function getNamespace() { return $this->mNamespace; }
+
/**
* Get the namespace text
+ *
* @return \type{\string} Namespace text
*/
public function getNsText() {
}
return $wgContLang->getNsText( $this->mNamespace );
}
+
/**
* Get the DB key with the initial letter case as specified by the user
+ *
* @return \type{\string} DB key
*/
function getUserCaseDBKey() {
return $this->mUserCaseDBKey;
}
+
/**
* Get the namespace text of the subject (rather than talk) page
+ *
* @return \type{\string} Namespace text
*/
public function getSubjectNsText() {
global $wgContLang;
return $wgContLang->getNsText( MWNamespace::getSubject( $this->mNamespace ) );
}
+
/**
* Get the namespace text of the talk page
+ *
* @return \type{\string} Namespace text
*/
public function getTalkNsText() {
global $wgContLang;
return( $wgContLang->getNsText( MWNamespace::getTalk( $this->mNamespace ) ) );
}
+
/**
* Could this title have a corresponding talk page?
+ *
* @return \type{\bool} TRUE or FALSE
*/
public function canTalk() {
return( MWNamespace::canTalk( $this->mNamespace ) );
}
+
/**
* Get the interwiki prefix (or null string)
+ *
* @return \type{\string} Interwiki prefix
*/
public function getInterwiki() { return $this->mInterwiki; }
+
/**
* Get the Title fragment (i.e.\ the bit after the #) in text form
+ *
* @return \type{\string} Title fragment
*/
public function getFragment() { return $this->mFragment; }
+
/**
* Get the fragment in URL form, including the "#" character if there is one
* @return \type{\string} Fragment in URL form
return '#' . Title::escapeFragmentForURL( $this->mFragment );
}
}
+
/**
* Get the default namespace index, for when there is no namespace
+ *
* @return \type{\int} Default namespace index
*/
public function getDefaultNamespace() { return $this->mDefaultNamespace; }
/**
* Get title for search index
+ *
* @return \type{\string} a stripped-down title string ready for the
* search index
*/
/**
* Get the prefixed database key form
+ *
* @return \type{\string} the prefixed title, with underscores and
* any interwiki and namespace prefixes
*/
/**
* Get the prefixed title with spaces.
* This is the form usually used for display
+ *
* @return \type{\string} the prefixed title, with spaces
*/
public function getPrefixedText() {
/**
* Get the prefixed title with spaces, plus any fragment
* (part beginning with '#')
+ *
* @return \type{\string} the prefixed title, with spaces and
* the fragment, including '#'
*/
/**
* Get the base name, i.e. the leftmost parts before the /
+ *
* @return \type{\string} Base name
*/
public function getBaseText() {
/**
* Get the lowest-level subpage name, i.e. the rightmost part after /
+ *
* @return \type{\string} Subpage name
*/
public function getSubpageText() {
/**
* Get a URL-encoded form of the subpage text
+ *
* @return \type{\string} URL-encoded subpage name
*/
public function getSubpageUrlForm() {
/**
* Get a URL-encoded title (not an actual URL) including interwiki
+ *
* @return \type{\string} the URL-encoded form
*/
public function getPrefixedURL() {
/**
* Get a URL with no fragment or server name. If this page is generated
* with action=render, $wgServer is prepended.
- * @param mixed $query an optional query string; if not specified,
+ *
+ * @param $query Mixed: an optional query string; if not specified,
* $wgArticlePath will be used. Can be specified as an associative array
* as well, e.g., array( 'action' => 'edit' ) (keys and values will be
* URL-escaped).
/**
* Get an HTML-escaped version of the URL form, suitable for
* using in a link, without a server name or fragment
+ *
* @param $query \type{\string} an optional query string
* @return \type{\string} the URL
*/
/**
* Get the edit URL for this Title
+ *
* @return \type{\string} the URL, or a null string if this is an
* interwiki link
*/
/**
* Get the HTML-escaped displayable text form.
* Used for the title field in <a> tags.
+ *
* @return \type{\string} the text, including any prefixes
*/
public function getEscapedText() {
/**
* Is this Title interwiki?
+ *
* @return \type{\bool}
*/
public function isExternal() { return ( $this->mInterwiki != '' ); }
/**
* Does the title correspond to a protected article?
+ *
* @param $action \type{\string} the action the page is protected from,
* by default checks all actions.
* @return \type{\bool}
/**
* Is this a conversion table for the LanguageConverter?
+ *
* @return \type{\bool}
*/
public function isConversionTable() {
/**
* Is $wgUser watching this page?
+ *
* @return \type{\bool}
*/
public function userIsWatching() {
/**
* Can $wgUser perform $action on this page?
+ *
* @param $action \type{\string} action that permission needs to be checked for
* @param $doExpensiveQueries \type{\bool} Set this to false to avoid doing unnecessary queries.
* @return \type{\bool}
/**
* Is this title subject to title protection?
+ *
* @return \type{\mixed} An associative array representing any existent title
* protection, or false if there's none.
*/
/**
* Update the title protection status
+ *
* @param $create_perm \type{\string} Permission required for creation
* @param $reason \type{\string} Reason for protection
* @param $expiry \type{\string} Expiry timestamp
/**
* Can $wgUser read this page?
- * @return \type{\bool} TRUE or FALSE
+ *
+ * @return \type{\bool}
* @todo fold these checks into userCan()
*/
public function userCanRead() {
/**
* Is this a talk page of some sort?
- * @return \type{\bool} TRUE or FALSE
+ *
+ * @return \type{\bool}
*/
public function isTalkPage() {
return MWNamespace::isTalk( $this->getNamespace() );
/**
* Is this a subpage?
- * @return \type{\bool} TRUE or FALSE
+ *
+ * @return \type{\bool}
*/
public function isSubpage() {
return MWNamespace::hasSubpages( $this->mNamespace )
/**
* Does this have subpages? (Warning, usually requires an extra DB query.)
- * @return \type{\bool} TRUE or FALSE
+ *
+ * @return \type{\bool}
*/
public function hasSubpages() {
if( !MWNamespace::hasSubpages( $this->mNamespace ) ) {
/**
* Get all subpages of this page.
+ *
* @param $limit Maximum number of subpages to fetch; -1 for no limit
* @return mixed TitleArray, or empty array if this page's namespace
* doesn't allow subpages
* Could this page contain custom CSS or JavaScript, based
* on the title?
*
- * @return \type{\bool} TRUE or FALSE
+ * @return \type{\bool}
*/
public function isCssOrJsPage() {
return $this->mNamespace == NS_MEDIAWIKI
/**
* Is this a .css or .js subpage of a user page?
- * @return \type{\bool} TRUE or FALSE
+ * @return \type{\bool}
*/
public function isCssJsSubpage() {
return ( NS_USER == $this->mNamespace and preg_match("/\\/.*\\.(?:css|js)$/", $this->mTextform ) );
}
+
/**
* Is this a *valid* .css or .js subpage of a user page?
* Check that the corresponding skin exists
- * @return \type{\bool} TRUE or FALSE
+ *
+ * @return \type{\bool}
*/
public function isValidCssJsSubpage() {
if ( $this->isCssJsSubpage() ) {
return false;
}
}
+
/**
* Trim down a .css or .js subpage title to get the corresponding skin name
+ *
* @return string containing skin name from .css or .js subpage title
*/
public function getSkinFromCssJsSubpage() {
$subpage = $subpage[ count( $subpage ) - 1 ];
return( str_replace( array( '.css', '.js' ), array( '', '' ), $subpage ) );
}
+
/**
* Is this a .css subpage of a user page?
- * @return \type{\bool} TRUE or FALSE
+ *
+ * @return \type{\bool}
*/
public function isCssSubpage() {
return ( NS_USER == $this->mNamespace && preg_match("/\\/.*\\.css$/", $this->mTextform ) );
}
+
/**
* Is this a .js subpage of a user page?
- * @return \type{\bool} TRUE or FALSE
+ *
+ * @return \type{\bool}
*/
public function isJsSubpage() {
return ( NS_USER == $this->mNamespace && preg_match("/\\/.*\\.js$/", $this->mTextform ) );
}
+
/**
* Protect css subpages of user pages: can $wgUser edit
* this page?
*
- * @return \type{\bool} TRUE or FALSE
+ * @return \type{\bool}
* @todo XXX: this might be better using restrictions
*/
public function userCanEditCssSubpage() {
* Protect js subpages of user pages: can $wgUser edit
* this page?
*
- * @return \type{\bool} TRUE or FALSE
+ * @return \type{\bool}
* @todo XXX: this might be better using restrictions
*/
public function userCanEditJsSubpage() {
/**
* Cascading protection: Get the source of any cascading restrictions on this page.
*
- * @param $get_pages \type{\bool} Whether or not to retrieve the actual pages that the restrictions have come from.
- * @return \type{\arrayof{mixed title array, restriction array}} Array of the Title objects of the pages from
- * which cascading restrictions have come, false for none, or true if such restrictions exist, but $get_pages was not set.
- * The restriction array is an array of each type, each of which contains an array of unique groups.
+ * @param $get_pages \type{\bool} Whether or not to retrieve the actual pages
+ * that the restrictions have come from.
+ * @return \type{\arrayof{mixed title array, restriction array}} Array of the Title
+ * objects of the pages from which cascading restrictions have come,
+ * false for none, or true if such restrictions exist, but $get_pages was not set.
+ * The restriction array is an array of each type, each of which contains a
+ * array of unique groups.
*/
public function getCascadeProtectionSources( $get_pages = true ) {
$pagerestrictions = array();
}
return array( $sources, $pagerestrictions );
}
-
+
/**
* Returns cascading restrictions for the current article
- * @return
+ *
+ * @return Boolean
*/
function areRestrictionsCascading() {
if (!$this->mRestrictionsLoaded) {
/**
* Loads a string into mRestrictions array
+ *
* @param $res \type{Resource} restrictions as an SQL result.
- * @param $oldFashionedRestrictions string comma-separated list of page restrictions from page table (pre 1.10)
+ * @param $oldFashionedRestrictions string comma-separated list of page
+ * restrictions from page table (pre 1.10)
*/
private function loadRestrictionsFromResultWrapper( $res, $oldFashionedRestrictions = null ) {
$rows = array();
$this->loadRestrictionsFromRows( $rows, $oldFashionedRestrictions );
}
-
+
/**
- * Compiles list of active page restrictions from both page table (pre 1.10) and page_restrictions table
+ * Compiles list of active page restrictions from both page table (pre 1.10)
+ * and page_restrictions table
+ *
* @param $rows array of db result objects
- * @param $oldFashionedRestrictions string comma-separated list of page restrictions from page table (pre 1.10)
+ * @param $oldFashionedRestrictions string comma-separated list of page
+ * restrictions from page table (pre 1.10)
*/
public function loadRestrictionsFromRows( $rows, $oldFashionedRestrictions = null ) {
$dbr = wfGetDB( DB_SLAVE );
/**
* Load restrictions from the page_restrictions table
- * @param $oldFashionedRestrictions string comma-separated list of page restrictions from page table (pre 1.10)
+ *
+ * @param $oldFashionedRestrictions string comma-separated list of page
+ * restrictions from page table (pre 1.10)
*/
public function loadRestrictions( $oldFashionedRestrictions = null ) {
if( !$this->mRestrictionsLoaded ) {
/**
* Get the expiry time for the restriction against a given action
+ *
* @return 14-char timestamp, or 'infinity' if the page is protected forever
* or not protected at all, or false if the action is not recognised.
*/
/**
* Is there a version of this page in the deletion archive?
+ *
* @return \type{\int} the number of archived revisions
*/
public function isDeleted() {
/**
* Is there a version of this page in the deletion archive?
- * @return bool
+ *
+ * @return Boolean
*/
public function isDeletedQuick() {
if( $this->getNamespace() < 0 ) {
/**
* Get the article ID for this Title from the link cache,
* adding it if necessary
+ *
* @param $flags \type{\int} a bit field; may be GAID_FOR_UPDATE to select
* for update
* @return \type{\int} the ID
/**
* Is this an article that is a redirect page?
* Uses link cache, adding it if necessary
+ *
* @param $flags \type{\int} a bit field; may be GAID_FOR_UPDATE to select for update
* @return \type{\bool}
*/
/**
* What is the length of this page?
* Uses link cache, adding it if necessary
+ *
* @param $flags \type{\int} a bit field; may be GAID_FOR_UPDATE to select for update
* @return \type{\bool}
*/
/**
* What is the page_latest field for this page?
+ *
* @param $flags \type{\int} a bit field; may be GAID_FOR_UPDATE to select for update
* @return \type{\int} or false if the page doesn't exist
*/
/**
* Updates page_touched for this page; called from LinksUpdate.php
+ *
* @return \type{\bool} true if the update succeded
*/
public function invalidateCache() {
* Returns a simple regex that will match on characters and sequences invalid in titles.
* Note that this doesn't pick up many things that could be wrong with titles, but that
* replacing this regex with something valid will make many titles valid.
+ *
* @return string regex string
*/
static function getTitleInvalidRegex() {
/**
* Capitalize a text string for a title if it belongs to a namespace that capitalizes
+ *
* @param $text string containing title to capitalize
- * $param $ns int namespace index, defaults to NS_MAIN
- * @return $text string containing capitalized title
+ * @param $ns int namespace index, defaults to NS_MAIN
+ * @return String containing capitalized title
*/
public static function capitalize( $text, $ns = NS_MAIN ) {
global $wgContLang;
* removes illegal characters, splits off the interwiki and
* namespace prefixes, sets the other forms, and canonicalizes
* everything.
+ *
* @return \type{\bool} true on success
*/
private function secureAndSplit() {
/**
* Get a Title object associated with the talk page of this article
+ *
* @return \type{Title} the object for the talk page
*/
public function getTalkPage() {
* WARNING: do not use this function on arbitrary user-supplied titles!
* On heavily-used templates it will max out the memory.
*
- * @param array $options may be FOR UPDATE
+ * @param $options Array: may be FOR UPDATE
+ * @param $table String: table name
+ * @param $prefix String: fields prefix
* @return \type{\arrayof{Title}} the Title objects linking here
*/
public function getLinksTo( $options = array(), $table = 'pagelinks', $prefix = 'pl' ) {
* WARNING: do not use this function on arbitrary user-supplied titles!
* On heavily-used templates it will max out the memory.
*
- * @param array $options may be FOR UPDATE
+ * @param $options Array: may be FOR UPDATE
* @return \type{\arrayof{Title}} the Title objects linking here
*/
public function getTemplateLinksTo( $options = array() ) {
/**
* Move this page without authentication
- * @param &$nt \type{Title} the new page Title
+ *
+ * @param $nt \type{Title} the new page Title
* @return \type{\mixed} true on success, getUserPermissionsErrors()-like array on failure
*/
public function moveNoAuth( &$nt ) {
/**
* Check whether a given move operation would be valid.
* Returns true if ok, or a getUserPermissionsErrors()-like array otherwise
- * @param &$nt \type{Title} the new title
+ *
+ * @param $nt \type{Title} the new title
* @param $auth \type{\bool} indicates whether $wgUser's permissions
* should be checked
* @param $reason \type{\string} is the log summary of the move, used for spam checking
/**
* Move a title to a new location
- * @param &$nt \type{Title} the new title
+ *
+ * @param $nt \type{Title} the new title
* @param $auth \type{\bool} indicates whether $wgUser's permissions
* should be checked
* @param $reason \type{\string} The reason for the move
* Move page to a title which is at present a redirect to the
* source page
*
- * @param &$nt \type{Title} the page to move to, which should currently
+ * @param $nt \type{Title} the page to move to, which should currently
* be a redirect
* @param $reason \type{\string} The reason for the move
* @param $createRedirect \type{\bool} Whether to leave a redirect at the old title.
/**
* Move page to non-existing title.
- * @param &$nt \type{Title} the new Title
+ *
+ * @param $nt \type{Title} the new Title
* @param $reason \type{\string} The reason for the move
* @param $createRedirect \type{\bool} Whether to create a redirect from the old title to the new title
* Ignored if the user doesn't have the suppressredirect right
/**
* Move this page's subpages to be subpages of $nt
+ *
* @param $nt Title Move target
* @param $auth bool Whether $wgUser's permissions should be checked
* @param $reason string The reason for the move
* Checks if this page is just a one-rev redirect.
* Adds lock, so don't use just for light purposes.
*
- * @return \type{\bool} TRUE or FALSE
+ * @return \type{\bool}
*/
public function isSingleRevRedirect() {
$dbw = wfGetDB( DB_MASTER );
* Checks if $this can be moved to a given Title
* - Selects for update, so don't call it unless you mean business
*
- * @param &$nt \type{Title} the new title to check
+ * @param $nt \type{Title} the new title to check
* @return \type{\bool} TRUE or FALSE
*/
public function isValidMoveTarget( $nt ) {
/**
* Get a tree of parent categories
+ *
* @param $children \type{\array} an array with the children in the keys, to check for circular refs
* @return \type{\array} Tree of parent categories
*/
/**
* Get the oldest revision timestamp of this page
*
- * @return string, MW timestamp
+ * @return String: MW timestamp
*/
public function getEarliestRevTime() {
$dbr = wfGetDB( DB_SLAVE );
/**
* Compare with another title.
*
- * @param \type{Title} $title
+ * @param $title \type{Title}
* @return \type{\bool} TRUE or FALSE
*/
public function equals( Title $title ) {
/**
* Callback for usort() to do title sorts by (namespace, title)
*
- * @return int result of string comparison, or namespace comparison
+ * @return Integer: result of string comparison, or namespace comparison
*/
public static function compare( $a, $b ) {
if( $a->getNamespace() == $b->getNamespace() ) {
* If you want to know if a title can be meaningfully viewed, you should
* probably call the isKnown() method instead.
*
- * @return \type{\bool} TRUE or FALSE
+ * @return \type{\bool}
*/
public function exists() {
return $this->getArticleId() != 0;
* existing code, but we might want to add an optional parameter to skip
* it and any other expensive checks.)
*
- * @return \type{\bool} TRUE or FALSE
+ * @return \type{\bool}
*/
public function isAlwaysKnown() {
if( $this->mInterwiki != '' ) {
* links to the title should be rendered as "bluelinks" (as opposed to
* "redlinks" to non-existent pages).
*
- * @return \type{\bool} TRUE or FALSE
+ * @return \type{\bool}
*/
public function isKnown() {
return $this->exists() || $this->isAlwaysKnown();
/**
* Is this in a namespace that allows actual pages?
*
- * @return \type{\bool} TRUE or FALSE
+ * @return \type{\bool}
* @internal note -- uses hardcoded namespace index instead of constants
*/
public function canExist() {
/**
* Get the last touched timestamp
- * @param Database $db, optional db
+ *
+ * @param $db DatabaseBase: optional db
* @return \type{\string} Last touched timestamp
*/
public function getTouched( $db = null ) {
/**
* Get the timestamp when this page was updated since the user last saw it.
- * @param User $user
- * @return mixed string/NULL
+ *
+ * @param $user User
+ * @return Mixed: string/null
*/
public function getNotificationTimestamp( $user = null ) {
global $wgUser, $wgShowUpdatedMarker;
/**
* Get the trackback URL for this page
+ *
* @return \type{\string} Trackback URL
*/
public function trackbackURL() {
/**
* Get the trackback RDF for this page
+ *
* @return \type{\string} Trackback RDF
*/
public function trackbackRDF() {
/**
* Generate strings used for xml 'id' names in monobook tabs
+ *
* @param $prepend string defaults to 'nstab-'
* @return \type{\string} XML 'id' name
*/
/**
* Returns true if this is a special page.
+ *
* @return boolean
*/
public function isSpecialPage( ) {
/**
* Returns true if this title resolves to the named special page
+ *
* @param $name \type{\string} The special page name
* @return boolean
*/
/**
* If the Title refers to a special page alias which is not the local default,
- * @return \type{Title} A new Title which points to the local default. Otherwise, returns $this.
+ *
+ * @return \type{Title} A new Title which points to the local default.
+ * Otherwise, returns $this.
*/
public function fixSpecialName() {
if ( $this->getNamespace() == NS_SPECIAL ) {
* In other words, is this a content page, for the purposes of calculating
* statistics, etc?
*
- * @return \type{\bool} TRUE or FALSE
+ * @return \type{\bool}
*/
public function isContentPage() {
return MWNamespace::isContent( $this->getNamespace() );
/**
* Check if this Title is a valid redirect target
*
- * @return \type{\bool} TRUE or FALSE
+ * @return \type{\bool}
*/
public function isValidRedirectTarget() {
global $wgInvalidRedirectTargets;
/**
* Get a backlink cache object
+ *
* @return object BacklinkCache
*/
function getBacklinkCache() {
/**
* Whether the magic words __INDEX__ and __NOINDEX__ function for
* this page.
- * @return Bool
+ *
+ * @return Boolean
*/
public function canUseNoindex(){
global $wgArticleRobotPolicies, $wgContentNamespaces,
/**
* Returns restriction types for the current Title
+ *
* @return array applicable restriction types
*/
public function getRestrictionTypes() {