r93942 MediaWiki - Code Review archive

Repository:MediaWiki
Revision:r93941‎ | r93942 | r93943 >
Date:00:33, 5 August 2011
Author:reedy
Status:ok
Tags:
Comment:
Add documentation

Minor whitespace/brace additions
Modified paths:
  • /trunk/phase3/includes/api/ApiFeedContributions.php (modified) (history)
  • /trunk/phase3/includes/parser/Parser.php (modified) (history)

Diff [purge]

Index: trunk/phase3/includes/parser/Parser.php
@@ -148,6 +148,7 @@
149149 var $mTplExpandCache; # empty-frame expansion cache
150150 var $mTplRedirCache, $mTplDomCache, $mHeadings, $mDoubleUnderscores;
151151 var $mExpensiveFunctionCount; # number of expensive parser function calls
 152+ var $mShowToc, $mForceTocPosition;
152153
153154 /**
154155 * @var User
@@ -181,6 +182,8 @@
182183
183184 /**
184185 * Constructor
 186+ *
 187+ * @param $conf array
185188 */
186189 public function __construct( $conf = array() ) {
187190 $this->mConf = $conf;
@@ -797,6 +800,10 @@
798801 * Add an item to the strip state
799802 * Returns the unique tag which must be inserted into the stripped text
800803 * The tag will be replaced with the original text in unstrip()
 804+ *
 805+ * @param $text string
 806+ *
 807+ * @return string
801808 */
802809 function insertStripItem( $text ) {
803810 $rnd = "{$this->mUniqPrefix}-item-{$this->mMarkerIndex}-" . self::MARKER_SUFFIX;
@@ -809,6 +816,10 @@
810817 * parse the wiki syntax used to render tables
811818 *
812819 * @private
 820+ *
 821+ * @param $text string
 822+ *
 823+ * @return string
813824 */
814825 function doTableStuff( $text ) {
815826 wfProfileIn( __METHOD__ );
@@ -1020,10 +1031,13 @@
10211032 * Helper function for doTableStuff(). This converts the structured array into html.
10221033 *
10231034 * @private
 1035+ *
 1036+ * @param $table array
 1037+ *
 1038+ * @return string
10241039 */
10251040 function generateTableHTML( &$table ) {
1026 - $return = "";
1027 - $return .= str_repeat( '<dl><dd>' , $table['indent'] );
 1041+ $return = str_repeat( '<dl><dd>' , $table['indent'] );
10281042 $return .= '<table';
10291043 $return .= isset( $table['attributes'] ) ? $table['attributes'] : '';
10301044 $return .= '>';
@@ -1105,6 +1119,8 @@
11061120 * no numric elements and an array itself if not previously defined.
11071121 *
11081122 * @private
 1123+ *
 1124+ * @param $arr array
11091125 */
11101126 function &last ( &$arr ) {
11111127 for ( $i = count( $arr ); ( !isset( $arr[$i] ) && $i > 0 ); $i-- ) { }
@@ -1116,8 +1132,14 @@
11171133 * HTML. Only called for $mOutputType == self::OT_HTML.
11181134 *
11191135 * @private
 1136+ *
 1137+ * @param $text string
 1138+ * @param $isMain bool
 1139+ * @param $frame bool
 1140+ *
 1141+ * @return string
11201142 */
1121 - function internalParse( $text, $isMain = true, $frame=false ) {
 1143+ function internalParse( $text, $isMain = true, $frame = false ) {
11221144 wfProfileIn( __METHOD__ );
11231145
11241146 $origText = $text;
@@ -1183,6 +1205,10 @@
11841206 *
11851207 * DML
11861208 * @private
 1209+ *
 1210+ * @param $text string
 1211+ *
 1212+ * @return string
11871213 */
11881214 function doMagicLinks( $text ) {
11891215 wfProfileIn( __METHOD__ );
@@ -1256,7 +1282,10 @@
12571283
12581284 /**
12591285 * Make a free external link, given a user-supplied URL
1260 - * @return HTML
 1286+ *
 1287+ * @param $url string
 1288+ *
 1289+ * @return string HTML
12611290 * @private
12621291 */
12631292 function makeFreeExternalLink( $url ) {
@@ -1309,6 +1338,10 @@
13101339 * Parse headers and return html
13111340 *
13121341 * @private
 1342+ *
 1343+ * @param $text string
 1344+ *
 1345+ * @return string
13131346 */
13141347 function doHeadings( $text ) {
13151348 wfProfileIn( __METHOD__ );
@@ -1324,6 +1357,9 @@
13251358 /**
13261359 * Replace single quotes with HTML markup
13271360 * @private
 1361+ *
 1362+ * @param $text string
 1363+ *
13281364 * @return string the altered text
13291365 */
13301366 function doAllQuotes( $text ) {
@@ -1340,6 +1376,10 @@
13411377
13421378 /**
13431379 * Helper function for doAllQuotes()
 1380+ *
 1381+ * @param $text string
 1382+ *
 1383+ * @return string
13441384 */
13451385 public function doQuotes( $text ) {
13461386 $arr = preg_split( "/(''+)/", $text, -1, PREG_SPLIT_DELIM_CAPTURE );
@@ -1504,6 +1544,10 @@
15051545 * Make sure to run maintenance/parserTests.php if you change this code.
15061546 *
15071547 * @private
 1548+ *
 1549+ * @param $text string
 1550+ *
 1551+ * @return string
15081552 */
15091553 function replaceExternalLinks( $text ) {
15101554 global $wgContLang;
@@ -1580,9 +1624,9 @@
15811625 * (depending on configuration, namespace, and the URL's domain) and/or a
15821626 * target attribute (depending on configuration).
15831627 *
1584 - * @param $url String: optional URL, to extract the domain from for rel =>
 1628+ * @param $url String|bool optional URL, to extract the domain from for rel =>
15851629 * nofollow if appropriate
1586 - * @return Array: associative array of HTML attributes
 1630+ * @return Array associative array of HTML attributes
15871631 */
15881632 function getExternalLinkAttribs( $url = false ) {
15891633 $attribs = array();
@@ -1629,6 +1673,10 @@
16301674 /**
16311675 * Callback function used in replaceUnusualEscapes().
16321676 * Replaces unusual URL escape codes with their equivalent character
 1677+ *
 1678+ * @param $matches array
 1679+ *
 1680+ * @return string
16331681 */
16341682 private static function replaceUnusualEscapesCallback( $matches ) {
16351683 $char = urldecode( $matches[0] );
@@ -1647,6 +1695,10 @@
16481696 * make an image if it's allowed, either through the global
16491697 * option, through the exception, or through the on-wiki whitelist
16501698 * @private
 1699+ *
 1700+ * $param $url string
 1701+ *
 1702+ * @return string
16511703 */
16521704 function maybeMakeExternalImage( $url ) {
16531705 $imagesfrom = $this->mOptions->getAllowExternalImagesFrom();
@@ -1693,6 +1745,9 @@
16941746
16951747 /**
16961748 * Process [[ ]] wikilinks
 1749+ *
 1750+ * @param $s string
 1751+ *
16971752 * @return String: processed text
16981753 *
16991754 * @private
@@ -2121,6 +2176,11 @@
21222177 * getCommon() returns the length of the longest common substring
21232178 * of both arguments, starting at the beginning of both.
21242179 * @private
 2180+ *
 2181+ * @param $st1 string
 2182+ * @param $st2 string
 2183+ *
 2184+ * @return int
21252185 */
21262186 function getCommon( $st1, $st2 ) {
21272187 $fl = strlen( $st1 );
@@ -2142,6 +2202,8 @@
21432203 * element appropriate to the prefix character passed into them.
21442204 * @private
21452205 *
 2206+ * @param $char char
 2207+ *
21462208 * @return string
21472209 */
21482210 function openList( $char ) {
@@ -2405,10 +2467,10 @@
24062468 * Split up a string on ':', ignoring any occurences inside tags
24072469 * to prevent illegal overlapping.
24082470 *
2409 - * @param $str String: the string to split
2410 - * @param &$before String: set to everything before the ':'
2411 - * @param &$after String: set to everything after the ':'
2412 - * return String: the position of the ':', or false if none found
 2471+ * @param $str String the string to split
 2472+ * @param &$before String set to everything before the ':'
 2473+ * @param &$after String set to everything after the ':'
 2474+ * @return String the position of the ':', or false if none found
24132475 */
24142476 function findColonNoLinks( $str, &$before, &$after ) {
24152477 wfProfileIn( __METHOD__ );
@@ -2573,8 +2635,10 @@
25742636 *
25752637 * @param $index integer
25762638 * @param $frame PPFrame
 2639+ *
 2640+ * @return string
25772641 */
2578 - function getVariableValue( $index, $frame=false ) {
 2642+ function getVariableValue( $index, $frame = false ) {
25792643 global $wgContLang, $wgSitename, $wgServer;
25802644 global $wgArticlePath, $wgScriptPath, $wgStylePath;
25812645
@@ -2879,8 +2943,9 @@
28802944 }
28812945 }
28822946
2883 - if ( $index )
 2947+ if ( $index ) {
28842948 $this->mVarCache[$index] = $value;
 2949+ }
28852950
28862951 return $value;
28872952 }
@@ -2932,6 +2997,8 @@
29332998 /**
29342999 * Return a three-element array: leading whitespace, string contents, trailing whitespace
29353000 *
 3001+ * @param $s string
 3002+ *
29363003 * @return array
29373004 */
29383005 public static function splitWhitespace( $s ) {
@@ -2957,11 +3024,11 @@
29583025 * self::OT_PREPROCESS: templates but not extension tags
29593026 * self::OT_HTML: all templates and extension tags
29603027 *
2961 - * @param $text String: the text to transform
 3028+ * @param $text String the text to transform
29623029 * @param $frame PPFrame Object describing the arguments passed to the template.
29633030 * Arguments may also be provided as an associative array, as was the usual case before MW1.12.
29643031 * Providing arguments this way may be useful for extensions wishing to perform variable replacement explicitly.
2965 - * @param $argsOnly Boolean: only do argument (triple-brace) expansion, not double-brace expansion
 3032+ * @param $argsOnly Boolean only do argument (triple-brace) expansion, not double-brace expansion
29663033 * @private
29673034 *
29683035 * @return string
@@ -2991,6 +3058,8 @@
29923059 /**
29933060 * Clean up argument array - refactored in 1.9 so parserfunctions can use it, too.
29943061 *
 3062+ * @param $args array
 3063+ *
29953064 * @return array
29963065 */
29973066 static function createAssocArgs( $args ) {
@@ -3394,6 +3463,8 @@
33953464 * Get the semi-parsed DOM representation of a template with a given title,
33963465 * and its redirect destination title. Cached.
33973466 *
 3467+ * @param $title Title
 3468+ *
33983469 * @return array
33993470 */
34003471 function getTemplateDom( $title ) {
@@ -3460,6 +3531,9 @@
34613532 * Static function to get a template
34623533 * Can be overridden via ParserOptions::setTemplateCallback().
34633534 *
 3535+ * @parma $title Title
 3536+ * @param $parser Parser
 3537+ *
34643538 * @return array
34653539 */
34663540 static function statelessFetchTemplate( $title, $parser = false ) {
@@ -3537,7 +3611,7 @@
35383612 * @param Title $title
35393613 * @param string $time MW timestamp
35403614 * @param string $sha1 base 36 SHA-1
3541 - * @return mixed File or false
 3615+ * @return File|false
35423616 */
35433617 function fetchFile( $title, $time = false, $sha1 = false ) {
35443618 $res = $this->fetchFileAndTitle( $title, $time, $sha1 );
@@ -3800,6 +3874,10 @@
38013875 /**
38023876 * Strip double-underscore items like __NOGALLERY__ and __NOTOC__
38033877 * Fills $this->mDoubleUnderscores, returns the modified text
 3878+ *
 3879+ * @param $text string
 3880+ *
 3881+ * @return string
38043882 */
38053883 function doDoubleUnderscore( $text ) {
38063884 wfProfileIn( __METHOD__ );
@@ -4281,6 +4359,11 @@
42824360 /**
42834361 * Pre-save transform helper function
42844362 * @private
 4363+ *
 4364+ * @param $text string
 4365+ * @param $user User
 4366+ *
 4367+ * @return string
42854368 */
42864369 function pstPass2( $text, $user ) {
42874370 global $wgContLang, $wgLocaltimezone;
@@ -4372,8 +4455,8 @@
43734456 * as it may have changed if it's the $wgParser.
43744457 *
43754458 * @param $user User
4376 - * @param $nickname String: nickname to use or false to use user's default nickname
4377 - * @param $fancySig Boolean: whether the nicknname is the complete signature
 4459+ * @param $nickname String|bool nickname to use or false to use user's default nickname
 4460+ * @param $fancySig Boolean|null whether the nicknname is the complete signature
43784461 * or null to use default value
43794462 * @return string
43804463 */
@@ -4435,7 +4518,7 @@
44364519 * 2) Substitute all transclusions
44374520 *
44384521 * @param $text String
4439 - * @param $parsing Whether we're cleaning (preferences save) or parsing
 4522+ * @param $parsing bool Whether we're cleaning (preferences save) or parsing
44404523 * @return String: signature text
44414524 */
44424525 function cleanSig( $text, $parsing = false ) {
@@ -4485,11 +4568,22 @@
44864569 /**
44874570 * Set up some variables which are usually set up in parse()
44884571 * so that an external function can call some class members with confidence
 4572+ *
 4573+ * @param $title Title|null
 4574+ * @param $options ParserOptions
 4575+ * @param $outputType
 4576+ * @param $clearState bool
44894577 */
44904578 public function startExternalParse( Title $title = null, ParserOptions $options, $outputType, $clearState = true ) {
44914579 $this->startParse( $title, $options, $outputType, $clearState );
44924580 }
44934581
 4582+ /**
 4583+ * @param $title Title|null
 4584+ * @param $options ParserOptions
 4585+ * @param $outputType
 4586+ * @param $clearState bool
 4587+ */
44944588 private function startParse( Title $title = null, ParserOptions $options, $outputType, $clearState = true ) {
44954589 $this->setTitle( $title );
44964590 $this->mOptions = $options;
@@ -4720,7 +4814,11 @@
47214815 * @todo FIXME: Update documentation. makeLinkObj() is deprecated.
47224816 * Replace <!--LINK--> link placeholders with actual links, in the buffer
47234817 * Placeholders created in Skin::makeLinkObj()
4724 - * Returns an array of link CSS classes, indexed by PDBK.
 4818+ *
 4819+ * @param $text string
 4820+ * @param $options int
 4821+ *
 4822+ * @return array of link CSS classes, indexed by PDBK.
47254823 */
47264824 function replaceLinkHolders( &$text, $options = 0 ) {
47274825 return $this->mLinkHolders->replace( $text );
@@ -4747,7 +4845,7 @@
47484846 * 'A tree'.
47494847 *
47504848 * @param string $text
4751 - * @param array $param
 4849+ * @param array $params
47524850 * @return string HTML
47534851 */
47544852 function renderImageGallery( $text, $params ) {
@@ -4832,6 +4930,10 @@
48334931 return $ig->toHTML();
48344932 }
48354933
 4934+ /**
 4935+ * @param $handler
 4936+ * @return array
 4937+ */
48364938 function getImageParams( $handler ) {
48374939 if ( $handler ) {
48384940 $handlerClass = get_class( $handler );
@@ -4877,7 +4979,7 @@
48784980 *
48794981 * @param $title Title
48804982 * @param $options String
4881 - * @param $holders LinkHolderArray
 4983+ * @param $holders LinkHolderArray|false
48824984 * @return string HTML
48834985 */
48844986 function makeImage( $title, $options, $holders = false ) {
@@ -5499,6 +5601,11 @@
55005602 /**
55015603 * strip/replaceVariables/unstrip for preprocessor regression testing
55025604 *
 5605+ * @param $text string
 5606+ * @param $title Title
 5607+ * @param $options ParserOptions
 5608+ * @param $outputType int
 5609+ *
55035610 * @return string
55045611 */
55055612 function testSrvus( $text, Title $title, ParserOptions $options, $outputType = self::OT_HTML ) {
@@ -5510,10 +5617,22 @@
55115618 return $text;
55125619 }
55135620
 5621+ /**
 5622+ * @param $text string
 5623+ * @param $title Title
 5624+ * @param $options ParserOptions
 5625+ * @return string
 5626+ */
55145627 function testPst( $text, Title $title, ParserOptions $options ) {
55155628 return $this->preSaveTransform( $text, $title, $options->getUser(), $options );
55165629 }
55175630
 5631+ /**
 5632+ * @param $text
 5633+ * @param $title Title
 5634+ * @param $options ParserOptions
 5635+ * @return string
 5636+ */
55185637 function testPreprocess( $text, Title $title, ParserOptions $options ) {
55195638 return $this->testSrvus( $text, $title, $options, self::OT_PREPROCESS );
55205639 }
@@ -5529,6 +5648,9 @@
55305649 * two strings will be replaced with the value returned by the callback in
55315650 * each case.
55325651 *
 5652+ * @param $s string
 5653+ * @param $callback
 5654+ *
55335655 * @return string
55345656 */
55355657 function markerSkipCallback( $s, $callback ) {
@@ -5567,6 +5689,8 @@
55685690 * unserializeHalfParsedText(). The text can then be safely incorporated into
55695691 * the return value of a parser hook.
55705692 *
 5693+ * @param $text string
 5694+ *
55715695 * @return array
55725696 */
55735697 function serializeHalfParsedText( $text ) {
Index: trunk/phase3/includes/api/ApiFeedContributions.php
@@ -99,7 +99,7 @@
100100 if( $title ) {
101101 $date = $row->rev_timestamp;
102102 $comments = $title->getTalkPage()->getFullURL();
103 - $revision = Revision::newFromRow( $row);
 103+ $revision = Revision::newFromRow( $row );
104104
105105 return new FeedItem(
106106 $title->getPrefixedText(),

Status & tagging log