r61647 MediaWiki - Code Review archive

Repository:MediaWiki
Revision:< r61646‎ | r61647 | r61648 >
Date:21:58, 28 January 2010
Author:ialex
Status:ok
Tags:
Comment:
Step one in fixing OutputPage's documentation:
* Groupped methods by function
* Added documentation
* Fixed some doxygen warnings
* Some little style fixes
(more to come)
Modified paths:
  • /trunk/phase3/includes/OutputPage.php (modified) (history)

Diff [purge]

Index: trunk/phase3/includes/OutputPage.php
——@@ -57,6 +57,7 @@
5858 private $mVaryHeader = array( 'Accept-Encoding' => array('list-contains=gzip'),
5959 'Cookie' => null );
6060
 61+
6162 /**
6263 * Constructor
6364 * Initialise private variables
——@@ -66,12 +67,23 @@
6768 $this->mAllowUserJs = $wgAllowUserJs;
6869 }
6970
 71+ /**
 72+ * Redirect to $url rather than displaying the normal page
 73+ *
 74+ * @param $url String: URL
 75+ * @param $responsecode String: HTTP status code
 76+ */
7077 public function redirect( $url, $responsecode = '302' ) {
7178 # Strip newlines as a paranoia check for header injection in PHP<5.1.2
7279 $this->mRedirect = str_replace( "\n", '', $url );
7380 $this->mRedirectCode = $responsecode;
7481 }
7582
 83+ /**
 84+ * Get the URL to redirect to, or an empty string if not redirect URL set
 85+ *
 86+ * @return String
 87+ */
7688 public function getRedirect() {
7789 return $this->mRedirect;
7890 }
——@@ -79,11 +91,14 @@
8092 /**
8193 * Set the HTTP status code to send with the output.
8294 *
83 - * @param int $statusCode
 95+ * @param $statusCode Integer
8496 * @return nothing
8597 */
86 - function setStatusCode( $statusCode ) { $this->mStatusCode = $statusCode; }
 98+ public function setStatusCode( $statusCode ) {
 99+ $this->mStatusCode = $statusCode;
 100+ }
87101
 102+
88103 /**
89104 * Add a new <meta> tag
90105 * To add an http-equiv meta tag, precede the name with "http:"
——@@ -95,19 +110,56 @@
96111 array_push( $this->mMetatags, array( $name, $val ) );
97112 }
98113
 114+ /**
 115+ * Add a keyword or a list of keywords in the page header
 116+ *
 117+ * @param $text String or array of strings
 118+ */
99119 function addKeyword( $text ) {
100 - if( is_array( $text )) {
 120+ if( is_array( $text ) ) {
101121 $this->mKeywords = array_merge( $this->mKeywords, $text );
102122 } else {
103123 array_push( $this->mKeywords, $text );
104124 }
105125 }
 126+
 127+ /**
 128+ * Add a new \<link\> tag to the page header
 129+ *
 130+ * @param $linkarr Array: associative array of attributes.
 131+ */
 132+ function addLink( $linkarr ) {
 133+ array_push( $this->mLinktags, $linkarr );
 134+ }
 135+
 136+ /**
 137+ * Add a new \<link\> with "rel" attribute set to "meta"
 138+ *
 139+ * @param $linkarr Array: associative array mapping attribute names to their
 140+ * values, both keys and values will be escaped, and the
 141+ * "rel" attribute will be automatically added
 142+ */
 143+ function addMetadataLink( $linkarr ) {
 144+ # note: buggy CC software only reads first "meta" link
 145+ static $haveMeta = false;
 146+ $linkarr['rel'] = $haveMeta ? 'alternate meta' : 'meta';
 147+ $this->addLink( $linkarr );
 148+ $haveMeta = true;
 149+ }
 150+
 151+
 152+ /**
 153+ * Add raw HTML to the list of scripts (including \<script\> tag, etc.)
 154+ *
 155+ * @param $script String: raw HTML
 156+ */
106157 function addScript( $script ) {
107158 $this->mScripts .= $script . "\n";
108159 }
109160
110161 /**
111162 * Register and add a stylesheet from an extension directory.
 163+ *
112164 * @param $url String path to sheet. Provide either a full url (beginning
113165 * with 'http', etc) or a relative path from the document root
114166 * (beginning with '/'). Otherwise it behaves identically to
——@@ -118,10 +170,21 @@
119171 }
120172
121173 /**
 174+ * Get all links added by extensions
 175+ *
 176+ * @return Array
 177+ */
 178+ function getExtStyle() {
 179+ return $this->mExtStyles;
 180+ }
 181+
 182+ /**
122183 * Add a JavaScript file out of skins/common, or a given relative path.
123 - * @param string $file filename in skins/common or complete on-server path (/foo/bar.js)
 184+ *
 185+ * @param $file String: filename in skins/common or complete on-server path
 186+ * (/foo/bar.js)
124187 */
125 - function addScriptFile( $file ) {
 188+ public function addScriptFile( $file ) {
126189 global $wgStylePath, $wgStyleVersion;
127190 if( substr( $file, 0, 1 ) == '/' ) {
128191 $path = $file;
——@@ -133,19 +196,27 @@
134197
135198 /**
136199 * Add a self-contained script tag with the given contents
137 - * @param string $script JavaScript text, no <script> tags
 200+ *
 201+ * @param $script String: JavaScript text, no <script> tags
138202 */
139 - function addInlineScript( $script ) {
 203+ public function addInlineScript( $script ) {
140204 $this->mScripts .= Html::inlineScript( "\n$script\n" ) . "\n";
141205 }
142206
143207 /**
144208 * Get all registered JS and CSS tags for the header.
 209+ *
 210+ * @return String
145211 */
146212 function getScript() {
147213 return $this->mScripts . $this->getHeadItems();
148214 }
149215
 216+ /**
 217+ * Get all header items in a string
 218+ *
 219+ * @return String
 220+ */
150221 function getHeadItems() {
151222 $s = '';
152223 foreach ( $this->mHeadItems as $item ) {
——@@ -154,36 +225,56 @@
155226 return $s;
156227 }
157228
158 - function addHeadItem( $name, $value ) {
 229+ /**
 230+ * Add or replace an header item to the output
 231+ *
 232+ * @param $name String: item name
 233+ * @param $value String: raw HTML
 234+ */
 235+ public function addHeadItem( $name, $value ) {
159236 $this->mHeadItems[$name] = $value;
160237 }
161238
162 - function hasHeadItem( $name ) {
 239+ /**
 240+ * Check if the header item $name is already set
 241+ *
 242+ * @param $name String: item name
 243+ * @return Boolean
 244+ */
 245+ public function hasHeadItem( $name ) {
163246 return isset( $this->mHeadItems[$name] );
164247 }
165248
166 - function setETag($tag) { $this->mETag = $tag; }
167 - function setArticleBodyOnly($only) { $this->mArticleBodyOnly = $only; }
168 - function getArticleBodyOnly() { return $this->mArticleBodyOnly; }
169 -
170 - function addLink( $linkarr ) {
171 - # $linkarr should be an associative array of attributes. We'll escape on output.
172 - array_push( $this->mLinktags, $linkarr );
 249+ /**
 250+ * Set the value of the ETag HTTP header, only used if $wgUseETag is true
 251+ *
 252+ * @param $tag String: value of "ETag" header
 253+ */
 254+ function setETag( $tag ) {
 255+ $this->mETag = $tag;
173256 }
174257
175 - # Get all links added by extensions
176 - function getExtStyle() {
177 - return $this->mExtStyles;
 258+ /**
 259+ * Set whether the output should only contain the body of the article,
 260+ * without any skin, sidebar, etc.
 261+ * Used e.g. when calling with "action=raw".
 262+ *
 263+ * @param $only Boolean: whether to output only the body of the article
 264+ */
 265+ public function setArticleBodyOnly( $only ) {
 266+ $this->mArticleBodyOnly = $only;
178267 }
179268
180 - function addMetadataLink( $linkarr ) {
181 - # note: buggy CC software only reads first "meta" link
182 - static $haveMeta = false;
183 - $linkarr['rel'] = ($haveMeta) ? 'alternate meta' : 'meta';
184 - $this->addLink( $linkarr );
185 - $haveMeta = true;
 269+ /**
 270+ * Return whether the output will contain only the body of the article
 271+ *
 272+ * @return Boolean
 273+ */
 274+ public function getArticleBodyOnly() {
 275+ return $this->mArticleBodyOnly;
186276 }
187277
 278+
188279 /**
189280 * checkLastModified tells the client to use the client-cached page if
190281 * possible. If sucessful, the OutputPage is disabled so that
——@@ -191,9 +282,9 @@
192283 *
193284 * Side effect: sets mLastModified for Last-Modified header
194285 *
195 - * @return bool True iff cache-ok headers was sent.
 286+ * @return Boolean: true iff cache-ok headers was sent.
196287 */
197 - function checkLastModified( $timestamp ) {
 288+ public function checkLastModified( $timestamp ) {
198289 global $wgCachePages, $wgCacheEpoch, $wgUser, $wgRequest;
199290
200291 if ( !$timestamp || $timestamp == '19700101000000' ) {
——@@ -273,20 +364,11 @@
274365 return true;
275366 }
276367
277 - function setPageTitleActionText( $text ) {
278 - $this->mPageTitleActionText = $text;
279 - }
280368
281 - function getPageTitleActionText () {
282 - if ( isset( $this->mPageTitleActionText ) ) {
283 - return $this->mPageTitleActionText;
284 - }
285 - }
286 -
287369 /**
288370 * Set the robot policy for the page: <http://www.robotstxt.org/meta.html>
289371 *
290 - * @param $policy string The literal string to output as the contents of
 372+ * @param $policy String: the literal string to output as the contents of
291373 * the meta tag. Will be parsed according to the spec and output in
292374 * standardized form.
293375 * @return null
——@@ -296,10 +378,10 @@
297379
298380 if( isset( $policy['index'] ) ){
299381 $this->setIndexPolicy( $policy['index'] );
300 - }
 382+ }
301383 if( isset( $policy['follow'] ) ){
302384 $this->setFollowPolicy( $policy['follow'] );
303 - }
 385+ }
304386 }
305387
306388 /**
——@@ -320,7 +402,7 @@
321403 * Set the follow policy for the page, but leave the index policy un-
322404 * touched.
323405 *
324 - * @param $policy string Either 'follow' or 'nofollow'.
 406+ * @param $policy String: either 'follow' or 'nofollow'.
325407 * @return null
326408 */
327409 public function setFollowPolicy( $policy ) {
——@@ -330,7 +412,29 @@
331413 }
332414 }
333415
 416+
334417 /**
 418+ * Set the new value of the "action text", this will be added to the
 419+ * "HTML title", separated from it with " - ".
 420+ *
 421+ * @param $text String: new value of the "action text"
 422+ */
 423+ public function setPageTitleActionText( $text ) {
 424+ $this->mPageTitleActionText = $text;
 425+ }
 426+
 427+ /**
 428+ * Get the value of the "action text"
 429+ *
 430+ * @return String
 431+ */
 432+ public function getPageTitleActionText() {
 433+ if ( isset( $this->mPageTitleActionText ) ) {
 434+ return $this->mPageTitleActionText;
 435+ }
 436+ }
 437+
 438+ /**
335439 * "HTML title" means the contents of <title>. It is stored as plain, unescaped text and will be run through htmlspecialchars in the skin file.
336440 */
337441 public function setHTMLTitle( $name ) {
——@@ -338,6 +442,15 @@
339443 }
340444
341445 /**
 446+ * Return the "HTML title", i.e. the content of the <title> tag.
 447+ *
 448+ * @return String
 449+ */
 450+ public function getHTMLTitle() {
 451+ return $this->mHTMLtitle;
 452+ }
 453+
 454+ /**
342455 * "Page title" means the contents of <h1>. It is stored as a valid HTML fragment.
343456 * This function allows good tags like <sup> in the <h1> tag, but not bad tags like <script>.
344457 * This function automatically sets <title> to the same content as <h1> but with all tags removed.
——@@ -358,33 +471,103 @@
359472 $this->setHTMLTitle( wfMsg( 'pagetitle', Sanitizer::stripAllTags( $nameWithTags ) ) );
360473 }
361474
 475+ /**
 476+ * Return the "page title", i.e. the content of the <h1> tag.
 477+ *
 478+ * @return String
 479+ */
 480+ public function getPageTitle() {
 481+ return $this->mPagetitle;
 482+ }
 483+
 484+ /**
 485+ * Set the Title object to use
 486+ *
 487+ * @param $t Title object
 488+ */
362489 public function setTitle( $t ) {
363490 $this->mTitle = $t;
364491 }
365492
 493+ /**
 494+ * Get the Title object used in this instance
 495+ *
 496+ * @return Title
 497+ */
366498 public function getTitle() {
367499 if ( $this->mTitle instanceof Title ) {
368500 return $this->mTitle;
369 - }
370 - else {
 501+ } else {
371502 wfDebug( __METHOD__ . ' called and $mTitle is null. Return $wgTitle for sanity' );
372503 global $wgTitle;
373504 return $wgTitle;
374505 }
375506 }
376507
377 - public function getHTMLTitle() { return $this->mHTMLtitle; }
378 - public function getPageTitle() { return $this->mPagetitle; }
379 - public function setSubtitle( $str ) { $this->mSubtitle = /*$this->parse(*/$str/*)*/; } // @bug 2514
380 - public function appendSubtitle( $str ) { $this->mSubtitle .= /*$this->parse(*/$str/*)*/; } // @bug 2514
381 - public function getSubtitle() { return $this->mSubtitle; }
382 - public function isArticle() { return $this->mIsarticle; }
383 - public function setPrintable() { $this->mPrintable = true; }
384 - public function isPrintable() { return $this->mPrintable; }
385 - public function disable() { $this->mDoNothing = true; }
386 - public function isDisabled() { return $this->mDoNothing; }
 508+ /**
 509+ * Replace the subtile with $str
 510+ *
 511+ * @param $str String: new value of the subtitle
 512+ */
 513+ public function setSubtitle( $str ) {
 514+ $this->mSubtitle = /*$this->parse(*/ $str /*)*/; // @bug 2514
 515+ }
387516
388517 /**
 518+ * Add $str to the subtitle
 519+ *
 520+ * @param $str String to add to the subtitle
 521+ */
 522+ public function appendSubtitle( $str ) {
 523+ $this->mSubtitle .= /*$this->parse(*/ $str /*)*/; // @bug 2514
 524+ }
 525+
 526+ /**
 527+ * Get the subtitle
 528+ *
 529+ * @return String
 530+ */
 531+ public function getSubtitle() {
 532+ return $this->mSubtitle;
 533+ }
 534+
 535+
 536+ /**
 537+ * Set the page as printable, i.e. it'll be displayed with with all
 538+ * print styles included
 539+ */
 540+ public function setPrintable() {
 541+ $this->mPrintable = true;
 542+ }
 543+
 544+ /**
 545+ * Return whether the page is "printable"
 546+ *
 547+ * @return Boolean
 548+ */
 549+ public function isPrintable() {
 550+ return $this->mPrintable;
 551+ }
 552+
 553+
 554+ /**
 555+ * Disable output completely, i.e. calling output() will have no effect
 556+ */
 557+ public function disable() {
 558+ $this->mDoNothing = true;
 559+ }
 560+
 561+ /**
 562+ * Return whether the output will be completely disabled
 563+ *
 564+ * @return Boolean
 565+ */
 566+ public function isDisabled() {
 567+ return $this->mDoNothing;
 568+ }
 569+
 570+
 571+ /**
389572 * Add or remove feed links in the page header
390573 * This is mainly kept for backward compatibility, see OutputPage::addFeedLink()
391574 * for the new version
——@@ -437,43 +620,100 @@
438621 * Should we output feed links for this page?
439622 * @return Boolean
440623 */
441 - public function isSyndicated() { return count($this->mFeedLinks) > 0; }
 624+ public function isSyndicated() {
 625+ return count( $this->mFeedLinks ) > 0;
 626+ }
442627
443 - public function getFeedAppendQuery() { return $this->mFeedLinksAppendQuery; }
 628+ /**
 629+ * Will currently always return null
 630+ *
 631+ * @return null
 632+ */
 633+ public function getFeedAppendQuery() {
 634+ return $this->mFeedLinksAppendQuery;
 635+ }
444636
 637+ /**
 638+ * Set whether the displayed content is related to the source of the
 639+ * corresponding article on the wiki
 640+ * Setting true will cause the change "article related" toggle to true
 641+ *
 642+ * @param $v Boolean
 643+ */
 644+ public function setArticleFlag( $v ) {
 645+ $this->mIsarticle = $v;
 646+ if ( $v ) {
 647+ $this->mIsArticleRelated = $v;
 648+ }
 649+ }
 650+
 651+ /**
 652+ * Return whether the content displayed page is related to the source of
 653+ * the corresponding article on the wiki
 654+ *
 655+ * @return Boolean
 656+ */
 657+ public function isArticle() {
 658+ return $this->mIsarticle;
 659+ }
 660+
 661+ /**
 662+ * Set whether this page is related an article on the wiki
 663+ * Setting false will cause the change of "article flag" toggle to false
 664+ *
 665+ * @param $v Boolean
 666+ */
445667 public function setArticleRelated( $v ) {
446668 $this->mIsArticleRelated = $v;
447669 if ( !$v ) {
448670 $this->mIsarticle = false;
449671 }
450672 }
451 - public function setArticleFlag( $v ) {
452 - $this->mIsarticle = $v;
453 - if ( $v ) {
454 - $this->mIsArticleRelated = $v;
455 - }
 673+
 674+ /**
 675+ * Return whether this page is related an article on the wiki
 676+ *
 677+ * @return Boolean
 678+ */
 679+ public function isArticleRelated() {
 680+ return $this->mIsArticleRelated;
456681 }
457682
458 - public function isArticleRelated() { return $this->mIsArticleRelated; }
459683
460 - public function getLanguageLinks() { return $this->mLanguageLinks; }
461 - public function addLanguageLinks($newLinkArray) {
 684+ /**
 685+ * Add new language links
 686+ *
 687+ * @param $newLinkArray Associative array mapping language code to the page
 688+ * name
 689+ */
 690+ public function addLanguageLinks( $newLinkArray ) {
462691 $this->mLanguageLinks += $newLinkArray;
463692 }
464 - public function setLanguageLinks($newLinkArray) {
 693+
 694+ /**
 695+ * Reset the language links and add new language links
 696+ *
 697+ * @param $newLinkArray Associative array mapping language code to the page
 698+ * name
 699+ */
 700+ public function setLanguageLinks( $newLinkArray ) {
465701 $this->mLanguageLinks = $newLinkArray;
466702 }
467703
468 - public function getCategoryLinks() {
469 - return $this->mCategoryLinks;
 704+ /**
 705+ * Get the list of language links
 706+ *
 707+ * @return Associative array mapping language code to the page name
 708+ */
 709+ public function getLanguageLinks() {
 710+ return $this->mLanguageLinks;
470711 }
471712
472 - public function getCategories() {
473 - return $this->mCategories;
474 - }
475713
476714 /**
477715 * Add an array of categories, with names in the keys
 716+ *
 717+ * @param $categories Associative array mapping category name to its sort key
478718 */
479719 public function addCategoryLinks( $categories ) {
480720 global $wgUser, $wgContLang;
——@@ -527,11 +767,37 @@
528768 }
529769 }
530770
531 - public function setCategoryLinks($categories) {
 771+ /**
 772+ * Reset the category links (but not the category list) and add $categories
 773+ *
 774+ * @param $categories Associative array mapping category name to its sort key
 775+ */
 776+ public function setCategoryLinks( $categories ) {
532777 $this->mCategoryLinks = array();
533 - $this->addCategoryLinks($categories);
 778+ $this->addCategoryLinks( $categories );
534779 }
535780
 781+ /**
 782+ * Get the list of category links, in a 2-D array with the following format:
 783+ * $arr[$type][] = $link, where $type is either "normal" or "hidden" (for
 784+ * hidden categories) and $link a HTML fragment with a link to the category
 785+ * page
 786+ *
 787+ * @return Array
 788+ */
 789+ public function getCategoryLinks() {
 790+ return $this->mCategoryLinks;
 791+ }
 792+
 793+ /**
 794+ * Get the list of category names this page belongs to
 795+ *
 796+ * @return Array of strings
 797+ */
 798+ public function getCategories() {
 799+ return $this->mCategories;
 800+ }
 801+
536802 public function suppressQuickbar() { $this->mSuppressQuickbar = true; }
537803 public function isQuickbarSuppressed() { return $this->mSuppressQuickbar; }
538804

Follow-up revisions

RevisionCommit summaryAuthorDate
r61690Step two in fixing OutputPage's documentation, more or less the same as r61647ialex21:32, 29 January 2010

Status & tagging log