From: Aryeh Gregor <simetrical@users.mediawiki.org>
Date: Tue, 7 Nov 2006 05:37:31 +0000 (+0000)
Subject: Add some documentation to OutputPage.php and specify public/private for most of its... 
X-Git-Tag: 1.31.0-rc.0~55266
X-Git-Url: http://git.cyclocoop.org/%28?a=commitdiff_plain;h=889ef5eab6327c22522e256f8f6796fd1e92a99d;p=lhc%2Fweb%2Fwiklou.git

Add some documentation to OutputPage.php and specify public/private for most of its member functions (practically all public anyway).  And replace one gratuitous use of strcmp with good old ===.
---

diff --git a/includes/OutputPage.php b/includes/OutputPage.php
index 56705642ce..a59ff3d357 100644
--- a/includes/OutputPage.php
+++ b/includes/OutputPage.php
@@ -54,12 +54,18 @@ class OutputPage {
 		$this->mNewSectionLink = false;
 	}
 	
-	function redirect( $url, $responsecode = '302' ) { 
+	public function redirect( $url, $responsecode = '302' ) {
 		# Strip newlines as a paranoia check for header injection in PHP<5.1.2
 		$this->mRedirect = str_replace( "\n", '', $url );
 		$this->mRedirectCode = $responsecode;
 	}
 
+	/**
+	 * Set the HTTP status code to send with the output.
+	 *
+	 * @param int $statusCode
+	 * @return nothing
+	 */
 	function setStatusCode( $statusCode ) { $this->mStatusCode = $statusCode; }
 
 	# To add an http-equiv meta tag, precede the name with "http:"
@@ -88,8 +94,9 @@ class OutputPage {
 	/**
 	 * checkLastModified tells the client to use the client-cached page if
 	 * possible. If sucessful, the OutputPage is disabled so that
-	 * any future call to OutputPage->output() have no effect. The method
-	 * returns true iff cache-ok headers was sent.
+	 * any future call to OutputPage->output() have no effect.
+	 *
+	 * @return bool True iff cache-ok headers was sent.
 	 */
 	function checkLastModified ( $timestamp ) {
 		global $wgCachePages, $wgCacheEpoch, $wgUser, $wgRequest;
@@ -165,9 +172,9 @@ class OutputPage {
 		}
 	}
 
-	function setRobotpolicy( $str ) { $this->mRobotpolicy = $str; }
-	function setHTMLTitle( $name ) {$this->mHTMLtitle = $name; }
-	function setPageTitle( $name ) {
+	public function setRobotpolicy( $str ) { $this->mRobotpolicy = $str; }
+	public function setHTMLTitle( $name ) {$this->mHTMLtitle = $name; }
+	public function setPageTitle( $name ) {
 		global $action, $wgContLang;
 		$name = $wgContLang->convert($name, true);
 		$this->mPagetitle = $name;
@@ -180,50 +187,50 @@ class OutputPage {
 
 		$this->setHTMLTitle( wfMsg( 'pagetitle', $name ) );
 	}
-	function getHTMLTitle() { return $this->mHTMLtitle; }
-	function getPageTitle() { return $this->mPagetitle; }
-	function setSubtitle( $str ) { $this->mSubtitle = /*$this->parse(*/$str/*)*/; } // @bug 2514
-	function getSubtitle() { return $this->mSubtitle; }
-	function isArticle() { return $this->mIsarticle; }
-	function setPrintable() { $this->mPrintable = true; }
-	function isPrintable() { return $this->mPrintable; }
-	function setSyndicated( $show = true ) { $this->mShowFeedLinks = $show; }
-	function isSyndicated() { return $this->mShowFeedLinks; }
-	function setOnloadHandler( $js ) { $this->mOnloadHandler = $js; }
-	function getOnloadHandler() { return $this->mOnloadHandler; }
-	function disable() { $this->mDoNothing = true; }
-
-	function setArticleRelated( $v ) {
+	public function getHTMLTitle() { return $this->mHTMLtitle; }
+	public function getPageTitle() { return $this->mPagetitle; }
+	public function setSubtitle( $str ) { $this->mSubtitle = /*$this->parse(*/$str/*)*/; } // @bug 2514
+	public function getSubtitle() { return $this->mSubtitle; }
+	public function isArticle() { return $this->mIsarticle; }
+	public function setPrintable() { $this->mPrintable = true; }
+	public function isPrintable() { return $this->mPrintable; }
+	public function setSyndicated( $show = true ) { $this->mShowFeedLinks = $show; }
+	public function isSyndicated() { return $this->mShowFeedLinks; }
+	public function setOnloadHandler( $js ) { $this->mOnloadHandler = $js; }
+	public function getOnloadHandler() { return $this->mOnloadHandler; }
+	public function disable() { $this->mDoNothing = true; }
+
+	public function setArticleRelated( $v ) {
 		$this->mIsArticleRelated = $v;
 		if ( !$v ) {
 			$this->mIsarticle = false;
 		}
 	}
-	function setArticleFlag( $v ) {
+	public function setArticleFlag( $v ) {
 		$this->mIsarticle = $v;
 		if ( $v ) {
 			$this->mIsArticleRelated = $v;
 		}
 	}
 
-	function isArticleRelated() { return $this->mIsArticleRelated; }
+	public function isArticleRelated() { return $this->mIsArticleRelated; }
 
-	function getLanguageLinks() { return $this->mLanguageLinks; }
-	function addLanguageLinks($newLinkArray) {
+	public function getLanguageLinks() { return $this->mLanguageLinks; }
+	public function addLanguageLinks($newLinkArray) {
 		$this->mLanguageLinks += $newLinkArray;
 	}
-	function setLanguageLinks($newLinkArray) {
+	public function setLanguageLinks($newLinkArray) {
 		$this->mLanguageLinks = $newLinkArray;
 	}
 
-	function getCategoryLinks() {
+	public function getCategoryLinks() {
 		return $this->mCategoryLinks;
 	}
 
 	/**
 	 * Add an array of categories, with names in the keys
 	 */
-	function addCategoryLinks($categories) {
+	public function addCategoryLinks($categories) {
 		global $wgUser, $wgContLang;
 
 		if ( !is_array( $categories ) ) {
@@ -243,25 +250,25 @@ class OutputPage {
 		}
 	}
 
-	function setCategoryLinks($categories) {
+	public function setCategoryLinks($categories) {
 		$this->mCategoryLinks = array();
 		$this->addCategoryLinks($categories);
 	}
 
-	function suppressQuickbar() { $this->mSuppressQuickbar = true; }
-	function isQuickbarSuppressed() { return $this->mSuppressQuickbar; }
+	public function suppressQuickbar() { $this->mSuppressQuickbar = true; }
+	public function isQuickbarSuppressed() { return $this->mSuppressQuickbar; }
 
-	function addHTML( $text ) { $this->mBodytext .= $text; }
-	function clearHTML() { $this->mBodytext = ''; }
-	function getHTML() { return $this->mBodytext; }
-	function debug( $text ) { $this->mDebugtext .= $text; }
+	public function addHTML( $text ) { $this->mBodytext .= $text; }
+	public function clearHTML() { $this->mBodytext = ''; }
+	public function getHTML() { return $this->mBodytext; }
+	public function debug( $text ) { $this->mDebugtext .= $text; }
 
 	/* @deprecated */
-	function setParserOptions( $options ) {
+	public function setParserOptions( $options ) {
 		return $this->parserOptions( $options );
 	}
 
-	function parserOptions( $options = null ) {
+	public function parserOptions( $options = null ) {
 		if ( !$this->mParserOptions ) {
 			$this->mParserOptions = new ParserOptions;
 		}
@@ -274,7 +281,7 @@ class OutputPage {
 	 * @param mixed $revid an integer, or NULL
 	 * @return mixed previous value
 	 */
-	function setRevisionId( $revid ) {
+	public function setRevisionId( $revid ) {
 		$val = is_null( $revid ) ? null : intval( $revid );
 		return wfSetVar( $this->mRevisionId, $val );
 	}
@@ -283,17 +290,20 @@ class OutputPage {
 	 * Convert wikitext to HTML and add it to the buffer
 	 * Default assumes that the current page title will
 	 * be used.
+	 *
+	 * @param string $text
+	 * @param bool   $linestart
 	 */
-	function addWikiText( $text, $linestart = true ) {
+	public function addWikiText( $text, $linestart = true ) {
 		global $wgTitle;
 		$this->addWikiTextTitle($text, $wgTitle, $linestart);
 	}
 
-	function addWikiTextWithTitle($text, &$title, $linestart = true) {
+	public function addWikiTextWithTitle($text, &$title, $linestart = true) {
 		$this->addWikiTextTitle($text, $title, $linestart);
 	}
 
-	function addWikiTextTitle($text, &$title, $linestart) {
+	private function addWikiTextTitle($text, &$title, $linestart) {
 		global $wgParser;
 		$fname = 'OutputPage:addWikiTextTitle';
 		wfProfileIn($fname);
@@ -304,7 +314,11 @@ class OutputPage {
 		wfProfileOut($fname);
 	}
 
-	function addParserOutputNoText( &$parserOutput ) {
+	/**
+	 * @todo document
+	 * @param ParserOutput object &$parserOutput
+	 */
+	public function addParserOutputNoText( &$parserOutput ) {
 		$this->mLanguageLinks += $parserOutput->getLanguageLinks();
 		$this->addCategoryLinks( $parserOutput->getCategories() );
 		$this->mNewSectionLink = $parserOutput->getNewSection();
@@ -322,6 +336,10 @@ class OutputPage {
 		wfRunHooks( 'OutputPageParserOutput', array( &$this, $parserOutput ) );
 	}
 
+	/**
+	 * @todo document
+	 * @param ParserOutput &$parserOutput
+	 */
 	function addParserOutput( &$parserOutput ) {
 		$this->addParserOutputNoText( $parserOutput );
 		$text =	$parserOutput->getText();
@@ -331,9 +349,13 @@ class OutputPage {
 
 	/**
 	 * Add wikitext to the buffer, assuming that this is the primary text for a page view
-	 * Saves the text into the parser cache if possible
+	 * Saves the text into the parser cache if possible.
+	 *
+	 * @param string  $text
+	 * @param Article $article
+	 * @param bool    $cache
 	 */
-	function addPrimaryWikiText( $text, $article, $cache = true ) {
+	public function addPrimaryWikiText( $text, $article, $cache = true ) {
 		global $wgParser, $wgUser;
 
 		$popts = $this->parserOptions();
@@ -351,8 +373,11 @@ class OutputPage {
 
 	/**
 	 * For anything that isn't primary text or interface message
+	 *
+	 * @param string $text
+	 * @param bool   $linestart Is this the start of a line?
 	 */
-	function addSecondaryWikiText( $text, $linestart = true ) {
+	public function addSecondaryWikiText( $text, $linestart = true ) {
 		global $wgTitle;
 		$popts = $this->parserOptions();
 		$popts->setTidy(true);
@@ -363,9 +388,10 @@ class OutputPage {
 
 	/**
 	 * Add the output of a QuickTemplate to the output buffer
+	 *
 	 * @param QuickTemplate $template
 	 */
-	function addTemplate( &$template ) {
+	public function addTemplate( &$template ) {
 		ob_start();
 		$template->execute();
 		$this->addHTML( ob_get_contents() );
@@ -374,8 +400,12 @@ class OutputPage {
 
 	/**
 	 * Parse wikitext and return the HTML.
+	 *
+	 * @param string $text
+	 * @param bool   $linestart Is this the start of a line?
+	 * @param bool   $interface ??
 	 */
-	function parse( $text, $linestart = true, $interface = false ) {
+	public function parse( $text, $linestart = true, $interface = false ) {
 		global $wgParser, $wgTitle;
 		$popts = $this->parserOptions();
 		if ( $interface) { $popts->setInterfaceMessage(true); }
@@ -386,12 +416,12 @@ class OutputPage {
 	}
 
 	/**
-	 * @param $article
-	 * @param $user
+	 * @param Article $article
+	 * @param User    $user
 	 *
-	 * @return bool
+	 * @return bool True if successful, else false.
 	 */
-	function tryParserCache( &$article, $user ) {
+	public function tryParserCache( &$article, $user ) {
 		$parserCache =& ParserCache::singleton();
 		$parserOutput = $parserCache->get( $article, $user );
 		if ( $parserOutput !== false ) {
@@ -403,18 +433,17 @@ class OutputPage {
 	}
 
 	/**
-	 * Set the maximum cache time on the Squid in seconds
-	 * @param $maxage
+	 * @param int $maxage Maximum cache time on the Squid, in seconds.
 	 */
-	function setSquidMaxage( $maxage ) {
+	public function setSquidMaxage( $maxage ) {
 		$this->mSquidMaxage = $maxage;
 	}
 
 	/**
 	 * Use enableClientCache(false) to force it to send nocache headers
-	 * @param $state
+	 * @param $state ??
 	 */
-	function enableClientCache( $state ) {
+	public function enableClientCache( $state ) {
 		return wfSetVar( $this->mEnableClientCache, $state );
 	}
 
@@ -424,7 +453,7 @@ class OutputPage {
 			&& $wgRequest->getText('uselang', false) === false;
 	}
 
-	function sendCacheControl() {
+	public function sendCacheControl() {
 		global $wgUseSquid, $wgUseESI, $wgUseETag, $wgSquidMaxage, $wgRequest;
 		$fname = 'OutputPage::sendCacheControl';
 
@@ -480,7 +509,7 @@ class OutputPage {
 	 * Finally, all the text has been munged and accumulated into
 	 * the object, let's actually output it:
 	 */
-	function output() {
+	public function output() {
 		global $wgUser, $wgOutputEncoding, $wgRequest;
 		global $wgContLanguageCode, $wgDebugRedirects, $wgMimeType;
 		global $wgJsMimeType, $wgStylePath, $wgUseAjax, $wgAjaxSearch, $wgScriptPath, $wgServer;
@@ -605,7 +634,11 @@ class OutputPage {
 		wfProfileOut( $fname );
 	}
 
-	function out( $ins ) {
+	/**
+	 * @todo document
+	 * @param string $ins
+	 */
+	public function out( $ins ) {
 		global $wgInputEncoding, $wgOutputEncoding, $wgContLang;
 		if ( 0 == strcmp( $wgInputEncoding, $wgOutputEncoding ) ) {
 			$outs = $ins;
@@ -616,7 +649,10 @@ class OutputPage {
 		print $outs;
 	}
 
-	function setEncodings() {
+	/**
+	 * @todo document
+	 */
+	public function setEncodings() {
 		global $wgInputEncoding, $wgOutputEncoding;
 		global $wgUser, $wgContLang;
 
@@ -630,19 +666,20 @@ class OutputPage {
 	}
 
 	/**
-	 * Returns a HTML comment with the elapsed time since request.
-	 * This method has no side effects.
-	 * Use wfReportTime() instead.
+	 * Deprecated, use wfReportTime() instead.
 	 * @return string
 	 * @deprecated
 	 */
-	function reportTime() {
+	public function reportTime() {
 		$time = wfReportTime();
 		return $time;
 	}
 
 	/**
-	 * Produce a "user is blocked" page
+	 * Produce a "user is blocked" page.
+	 *
+	 * @param bool $return Whether to have a "return to $wgTitle" message or not.
+	 * @return nothing
 	 */
 	function blockedPage( $return = true ) {
 		global $wgUser, $wgContLang, $wgTitle;
@@ -672,9 +709,13 @@ class OutputPage {
 	}
 
 	/**
-	 * Note: these arguments are keys into wfMsg(), not text!
+	 * Outputs a pretty page to explain why the request exploded.
+	 *
+	 * @param string $title Message key for page title.
+	 * @param string $msg   Message key for page text.
+	 * @return nothing
 	 */
-	function showErrorPage( $title, $msg ) {
+	public function showErrorPage( $title, $msg ) {
 		global $wgTitle;
 
 		$this->mDebugtext .= 'Original title: ' .
@@ -692,7 +733,7 @@ class OutputPage {
 	}
 
 	/** @obsolete */
-	function errorpage( $title, $msg ) {
+	public function errorpage( $title, $msg ) {
 		throw new ErrorPageError( $title, $msg );
 	}
 		
@@ -702,7 +743,7 @@ class OutputPage {
 	 *
 	 * @param mixed $version The version of MediaWiki needed to use the page
 	 */
-	function versionRequired( $version ) {
+	public function versionRequired( $version ) {
 		$this->setPageTitle( wfMsg( 'versionrequired', $version ) );
 		$this->setHTMLTitle( wfMsg( 'versionrequired', $version ) );
 		$this->setRobotpolicy( 'noindex,nofollow' );
@@ -715,9 +756,10 @@ class OutputPage {
 
 	/**
 	 * Display an error page noting that a given permission bit is required.
+	 *
 	 * @param string $permission key required
 	 */
-	function permissionRequired( $permission ) {
+	public function permissionRequired( $permission ) {
 		global $wgGroupPermissions, $wgUser;
 
 		$this->setPageTitle( wfMsg( 'badaccess' ) );
@@ -755,23 +797,25 @@ class OutputPage {
 	}
 
 	/**
+	 * Use permissionRequired.
 	 * @deprecated
 	 */
-	function sysopRequired() {
+	public function sysopRequired() {
 		throw new MWException( "Call to deprecated OutputPage::sysopRequired() method\n" );
 	}
 
 	/**
+	 * Use permissionRequired.
 	 * @deprecated
 	 */
-	function developerRequired() {
+	public function developerRequired() {
 		throw new MWException( "Call to deprecated OutputPage::developerRequired() method\n" );
 	}
 
 	/**
 	 * Produce the stock "please login to use the wiki" page
 	 */
-	function loginToUse() {
+	public function loginToUse() {
 		global $wgUser, $wgTitle, $wgContLang;
 
 		if( $wgUser->isLoggedIn() ) {
@@ -799,11 +843,16 @@ class OutputPage {
 	}
 
 	/** @obsolete */
-	function databaseError( $fname, $sql, $error, $errno ) {
+	public function databaseError( $fname, $sql, $error, $errno ) {
 		throw new MWException( "OutputPage::databaseError is obsolete\n" );
 	}
 
-	function readOnlyPage( $source = null, $protected = false ) {
+	/**
+	 * @todo document
+	 * @param bool  $protected Is the reason the page can't be reached because it's protected?
+	 * @param mixed $source
+	 */
+	public function readOnlyPage( $source = null, $protected = false ) {
 		global $wgUser, $wgReadOnlyFile, $wgReadOnly, $wgTitle;
 
 		$this->setRobotpolicy( 'noindex,nofollow' );
@@ -813,7 +862,7 @@ class OutputPage {
 			$skin = $wgUser->getSkin();
 			$this->setPageTitle( wfMsg( 'viewsource' ) );
 			$this->setSubtitle( wfMsg( 'viewsourcefor', $skin->makeKnownLinkObj( $wgTitle ) ) );
-			
+
 			# Determine if protection is due to the page being a system message
 			# and show an appropriate explanation
 			if( $wgTitle->getNamespace() == NS_MEDIAWIKI && !$wgUser->isAllowed( 'editinterface' ) ) {
@@ -832,7 +881,7 @@ class OutputPage {
 		}
 
 		if( is_string( $source ) ) {
-			if( strcmp( $source, '' ) == 0 ) {
+			if( $source === '' ) {
 				global $wgTitle;
 				if ( $wgTitle->getNamespace() == NS_MEDIAWIKI ) {
 					$source = wfMsgWeirdKey ( $wgTitle->getText() );
@@ -852,36 +901,36 @@ class OutputPage {
 	}
 
 	/** @obsolete */
-	function fatalError( $message ) { 
+	public function fatalError( $message ) {
 		throw new FatalError( $message ); 
 	}
 	
 	/** @obsolete */
-	function unexpectedValueError( $name, $val ) {
+	public function unexpectedValueError( $name, $val ) {
 		throw new FatalError( wfMsg( 'unexpected', $name, $val ) );
 	}
 
 	/** @obsolete */
-	function fileCopyError( $old, $new ) {
+	public function fileCopyError( $old, $new ) {
 		throw new FatalError( wfMsg( 'filecopyerror', $old, $new ) );
 	}
 
 	/** @obsolete */
-	function fileRenameError( $old, $new ) {
+	public function fileRenameError( $old, $new ) {
 		throw new FatalError( wfMsg( 'filerenameerror', $old, $new ) );
 	}
 
 	/** @obsolete */
-	function fileDeleteError( $name ) {
+	public function fileDeleteError( $name ) {
 		throw new FatalError( wfMsg( 'filedeleteerror', $name ) );
 	}
 
 	/** @obsolete */
-	function fileNotFoundError( $name ) {
+	public function fileNotFoundError( $name ) {
 		throw new FatalError( wfMsg( 'filenotfound', $name ) );
 	}
 
-	function showFatalError( $message ) {
+	public function showFatalError( $message ) {
 		$this->setPageTitle( wfMsg( "internalerror" ) );
 		$this->setRobotpolicy( "noindex,nofollow" );
 		$this->setArticleRelated( false );
@@ -890,23 +939,23 @@ class OutputPage {
 		$this->mBodytext = $message;
 	}
 
-	function showUnexpectedValueError( $name, $val ) {
+	public function showUnexpectedValueError( $name, $val ) {
 		$this->showFatalError( wfMsg( 'unexpected', $name, $val ) );
 	}
 
-	function showFileCopyError( $old, $new ) {
+	public function showFileCopyError( $old, $new ) {
 		$this->showFatalError( wfMsg( 'filecopyerror', $old, $new ) );
 	}
 
-	function showFileRenameError( $old, $new ) {
+	public function showFileRenameError( $old, $new ) {
 		$this->showFatalError( wfMsg( 'filerenameerror', $old, $new ) );
 	}
 
-	function showFileDeleteError( $name ) {
+	public function showFileDeleteError( $name ) {
 		$this->showFatalError( wfMsg( 'filedeleteerror', $name ) );
 	}
 
-	function showFileNotFoundError( $name ) {
+	public function showFileNotFoundError( $name ) {
 		$this->showFatalError( wfMsg( 'filenotfound', $name ) );
 	}
 
@@ -915,7 +964,7 @@ class OutputPage {
 	 * @param $auto automatically redirect the user after 10 seconds
 	 * @param $returnto page title to return to. Default is Main Page.
 	 */
-	function returnToMain( $auto = true, $returnto = NULL ) {
+	public function returnToMain( $auto = true, $returnto = NULL ) {
 		global $wgUser, $wgOut, $wgRequest;
 		
 		if ( $returnto == NULL ) {
@@ -948,8 +997,10 @@ class OutputPage {
 	/**
 	 * This function takes the title (first item of mGoodLinks), categories, existing and broken links for the page
 	 * and uses the first 10 of them for META keywords
+	 *
+	 * @param ParserOutput &$parserOutput
 	 */
-	function addKeywords( &$parserOutput ) {
+	private function addKeywords( &$parserOutput ) {
 		global $wgTitle;
 		$this->addKeyword( $wgTitle->getPrefixedText() );
 		$count = 1;
@@ -968,10 +1019,9 @@ class OutputPage {
 	}
 
 	/**
- 	 * @access private
-	 * @return string
+	 * @return string The doctype, opening <html>, and head element.
 	 */
-	function headElement() {
+	public function headElement() {
 		global $wgDocType, $wgDTD, $wgContLanguageCode, $wgOutputEncoding, $wgMimeType;
 		global $wgUser, $wgContLang, $wgUseTrackbacks, $wgTitle, $wgStyleVersion;
 
@@ -1014,7 +1064,10 @@ class OutputPage {
 		return $ret;
 	}
 
-	function getHeadLinks() {
+	/**
+	 * @return string HTML tag links to be put in the header.
+	 */
+	public function getHeadLinks() {
 		global $wgRequest;
 		$ret = '';
 		foreach ( $this->mMetatags as $tag ) {
@@ -1064,9 +1117,8 @@ class OutputPage {
 	 * Turn off regular page output and return an error reponse
 	 * for when rate limiting has triggered.
 	 * @todo i18n
-	 * @access public
 	 */
-	function rateLimited() {
+	public function rateLimited() {
 		global $wgOut;
 		$wgOut->disable();
 		wfHttpError( 500, 'Internal Server Error',
@@ -1079,7 +1131,7 @@ class OutputPage {
 	 *
 	 * @return bool True if the parser output instructs us to add one
 	 */
-	function showNewSectionLink() {
+	public function showNewSectionLink() {
 		return $this->mNewSectionLink;
 	}