r99112 MediaWiki - Code Review archive

Repository:MediaWiki
Revision:< r99111‎ | r99112 | r99113 >
Date:15:18, 6 October 2011
Author:reedy
Status:ok (Comments)
Tags:
Comment:
More documentation updates and additions

Added TODO to UserToggles.php
Modified paths:
  • /trunk/extensions/Translate/FFS.php (modified) (history)
  • /trunk/extensions/Translate/Groups.php (modified) (history)
  • /trunk/extensions/Translate/MessageChecks.php (modified) (history)
  • /trunk/extensions/Translate/MessageCollection.php (modified) (history)
  • /trunk/extensions/Translate/MessageGroups.php (modified) (history)
  • /trunk/extensions/Translate/RcFilter.php (modified) (history)
  • /trunk/extensions/Translate/ffs/MediaWikiComplexMessages.php (modified) (history)
  • /trunk/extensions/Translate/ffs/Xliff.php (modified) (history)
  • /trunk/extensions/Translate/scripts/cli.inc (modified) (history)
  • /trunk/extensions/Translate/scripts/poimport.php (modified) (history)
  • /trunk/extensions/Translate/specials/SpecialManageGroups.php (modified) (history)
  • /trunk/extensions/Translate/specials/SpecialTranslationStats.php (modified) (history)
  • /trunk/extensions/Translate/tag/MoveJob.php (modified) (history)
  • /trunk/extensions/Translate/tag/PageTranslationHooks.php (modified) (history)
  • /trunk/extensions/Translate/tag/TPParse.php (modified) (history)
  • /trunk/extensions/Translate/tag/TranslatablePage.php (modified) (history)
  • /trunk/extensions/Translate/utils/MessageGroupCache.php (modified) (history)
  • /trunk/extensions/Translate/utils/MessageGroupStats.php (modified) (history)
  • /trunk/extensions/Translate/utils/MessageHandle.php (modified) (history)
  • /trunk/extensions/Translate/utils/MessageIndex.php (modified) (history)
  • /trunk/extensions/Translate/utils/MessageWebImporter.php (modified) (history)
  • /trunk/extensions/Translate/utils/StatsTable.php (modified) (history)
  • /trunk/extensions/Translate/utils/StringMatcher.php (modified) (history)
  • /trunk/extensions/Translate/utils/TranslationHelpers.php (modified) (history)
  • /trunk/extensions/Translate/utils/UserToggles.php (modified) (history)

Diff [purge]

Index: trunk/extensions/Translate/MessageCollection.php
——@@ -194,6 +194,7 @@
195195 /**
196196 * Some statistics scripts for example loop the same collection over every
197197 * language. This is a shortcut which keeps tags and definitions.
 198+ * @param $code
198199 */
199200 public function resetForNewLanguage( $code ) {
200201 $this->code = $code;
——@@ -209,6 +210,8 @@
210211
211212 /**
212213 * For paging messages. One can count messages before and after slice.
 214+ * @param $offset
 215+ * @param $limit
213216 */
214217 public function slice( $offset, $limit ) {
215218 $this->keys = array_slice( $this->keys, $offset, $limit, true );
——@@ -594,20 +597,32 @@
595598
596599 /**
597600 * ArrayAccess methods. @{
 601+ * @param $offset
598602 * @return bool
599603 */
600604 public function offsetExists( $offset ) {
601605 return isset( $this->keys[$offset] );
602606 }
603607
 608+ /**
 609+ * @param $offset
 610+ * @return
 611+ */
604612 public function offsetGet( $offset ) {
605613 return $this->messages[$offset];
606614 }
607615
 616+ /**
 617+ * @param $offset
 618+ * @param $value
 619+ */
608620 public function offsetSet( $offset, $value ) {
609621 $this->messages[$offset] = $value;
610622 }
611623
 624+ /**
 625+ * @param $offset
 626+ */
612627 public function offsetUnset( $offset ) {
613628 unset( $this->keys[$offset] );
614629 }
——@@ -615,6 +630,7 @@
616631
617632 /**
618633 * Fail fast if trying to access unknown properties. @{
 634+ * @param $name
619635 */
620636 public function __get( $name ) {
621637 throw new MWException( __METHOD__ . ": Trying to access unknown property $name" );
Index: trunk/extensions/Translate/scripts/cli.inc
——@@ -69,6 +69,8 @@
7070 /**
7171 * Output a warning message to command line (if available).
7272 * @see STDOUT
 73+ * @param $message
 74+ * @param null $channel
7375 */
7476 function STDERR( $message, $channel = null ) {
7577 STDOUT( $message, $channel, true );
Index: trunk/extensions/Translate/scripts/poimport.php
——@@ -226,6 +226,9 @@
227227
228228 /**
229229 * Actually adds the new translation.
 230+ * @param $namespace
 231+ * @param $page
 232+ * @param $text
230233 */
231234 private function updateMessage( $namespace, $page, $text ) {
232235 $title = Title::makeTitleSafe( $namespace, $page );
Index: trunk/extensions/Translate/MessageChecks.php
——@@ -101,6 +101,7 @@
102102 /**
103103 * Adds one tests for this checker.
104104 * @see setChecks()
 105+ * @param $check
105106 */
106107 public function addCheck( $check ) {
107108 if ( is_callable( $check ) ) {
Index: trunk/extensions/Translate/FFS.php
——@@ -518,7 +518,7 @@
519519 /**
520520 * Message keys format.
521521 *
522 - * @param $string
 522+ * @param $key string
523523 *
524524 * @return string
525525 */
Index: trunk/extensions/Translate/MessageGroups.php
——@@ -215,10 +215,16 @@
216216 /**
217217 * Returns path to the file where translation of language code $code are.
218218 *
 219+ * @param $code
219220 * @return Path to the file or false if not applicable.
220221 */
221222 public function getMessageFile( $code ) { return false; }
222223 public function getPath() { return false; }
 224+
 225+ /**
 226+ * @param $code
 227+ * @return bool|string
 228+ */
223229 public function getMessageFileWithPath( $code ) {
224230 $path = $this->getPath();
225231 $file = $this->getMessageFile( $code );
——@@ -467,12 +473,18 @@
468474 /**
469475 * Extensions have almost always a localised description message and
470476 * address to extension homepage.
 477+ * @param $key
 478+ * @param $url
471479 */
472480 public function setDescriptionMsg( $key, $url ) {
473481 $this->descriptionKey = $key;
474482 $this->descriptionUrl = $url;
475483 }
476484
 485+ /**
 486+ * @param $key
 487+ * @param $url
 488+ */
477489 protected function setDescriptionMsgReal( $key, $url ) {
478490 $this->description = '';
479491
——@@ -1158,6 +1170,10 @@
11591171 /**
11601172 * Function do do $array[level1][level2]...[levelN][$key] = $value, if we have
11611173 * the indexes in an array.
 1174+ * @param $array
 1175+ * @param $indexes array
 1176+ * @param $key
 1177+ * @param $value
11621178 */
11631179 public static function deepArraySet( &$array, array $indexes, $key, $value ) {
11641180 foreach ( $indexes as $index ) {
Index: trunk/extensions/Translate/tag/TranslatablePage.php
——@@ -434,6 +434,7 @@
435435 * Adds a tag which indicates that this page is
436436 * suitable for translation.
437437 * @param $revision integer
 438+ * @param null $value
438439 */
439440 public function addMarkedTag( $revision, $value = null ) {
440441 $this->addTag( 'tp:mark', $revision, $value );
Index: trunk/extensions/Translate/tag/TPParse.php
——@@ -224,6 +224,8 @@
225225 * Replaces variables from given text.
226226 * @todo Is plain str_replace not enough (even the loop is not needed)?
227227 *
 228+ * @param $variables array
 229+ * @param $text string
228230 * @return string
229231 */
230232 protected static function replaceVariables( $variables, $text ) {
Index: trunk/extensions/Translate/tag/PageTranslationHooks.php
——@@ -100,16 +100,15 @@
101101 }
102102
103103 /**
104 - * @static
105104 * @param $article Article
106105 * @param $user User
107 - * @param $text
108 - * @param $summary
109 - * @param $minor
110 - * @param $_
111 - * @param $_
112 - * @param $flags
113 - * @param $revision
 106+ * @param $text
 107+ * @param $summary
 108+ * @param $minor
 109+ * @param $_
 110+ * @param $_
 111+ * @param $flags
 112+ * @param $revision
114113 * @return bool
115114 */
116115 public static function onSectionSave( $article, $user, $text, $summary, $minor,
Index: trunk/extensions/Translate/tag/MoveJob.php
——@@ -168,6 +168,7 @@
169169
170170 /**
171171 * Adapted from wfSuppressWarnings to allow not leaving redirects.
 172+ * @param $end bool
172173 */
173174 public static function forceRedirects( $end = false ) {
174175 static $suppressCount = 0;
Index: trunk/extensions/Translate/utils/MessageHandle.php
——@@ -22,8 +22,7 @@
2323
2424 /**
2525 * Check if a title is in a message namespace.
26 - * @param $title Title
27 - * @return \bool If title is in a message namespace.
 26+ * @return bool If title is in a message namespace.
2827 */
2928 public function isMessageNamespace() {
3029 global $wgTranslateMessageNamespaces;
——@@ -111,8 +110,7 @@
112111
113112 /**
114113 * Check if a title is marked as fuzzy.
115 - * @param $title Title
116 - * @return \bool If title is marked fuzzy.
 114+ * @return bool If title is marked fuzzy.
117115 */
118116 public function isFuzzy() {
119117 $dbr = wfGetDB( DB_SLAVE );
Index: trunk/extensions/Translate/utils/UserToggles.php
——@@ -17,11 +17,14 @@
1818 * Add 'translate-pref-nonewsletter' preference.
1919 * This is actually specific to translatewiki.net
2020 *
21 - * @return \bool true
 21+ * @param $user User
 22+ * @param $preferences array
 23+ * @return bool true
2224 */
2325 public static function onGetPreferences( $user, &$preferences ) {
2426 global $wgEnableEmail, $wgUser, $wgEnotifRevealEditorAddress;
2527
 28+ // TODO: Shouldn't we use $user here?
2629 // Only show is e-mail is enabled and user has a confirmed e-mail address.
2730 if ( $wgEnableEmail && $wgUser->isEmailConfirmed() ) {
2831 // 'translate-pref-nonewsletter' is used as opt-out for
Index: trunk/extensions/Translate/utils/MessageWebImporter.php
——@@ -76,6 +76,7 @@
7777
7878 /**
7979 * Group is either MessageGroup object or group id.
 80+ * @param $group MessagerGroup|string
8081 */
8182 public function setGroup( $group ) {
8283 if ( $group instanceof MessageGroup ) {
——@@ -93,10 +94,16 @@
9495 $this->code = $code;
9596 }
9697
 98+ /**
 99+ * @return String
 100+ */
97101 protected function getAction() {
98102 return $this->getTitle()->getFullURL();
99103 }
100104
 105+ /**
 106+ * @return string
 107+ */
101108 protected function doHeader() {
102109 global $wgOut;
103110 $wgOut->addModules( 'ext.translate' );
——@@ -114,10 +121,16 @@
115122 Html::hidden( 'process', 1 );
116123 }
117124
 125+ /**
 126+ * @return string
 127+ */
118128 protected function doFooter() {
119129 return '</form>';
120130 }
121131
 132+ /**
 133+ * @return bool
 134+ */
122135 protected function allowProcess() {
123136 global $wgRequest;
124137
——@@ -130,6 +143,9 @@
131144 return false;
132145 }
133146
 147+ /**
 148+ * @return array
 149+ */
134150 protected function getActions() {
135151 if ( $this->code === 'en' ) {
136152 return array( 'import', 'fuzzy', 'ignore' );
——@@ -138,6 +154,11 @@
139155 }
140156 }
141157
 158+ /**
 159+ * @param $fuzzy bool
 160+ * @param $action
 161+ * @return string
 162+ */
142163 protected function getDefaultAction( $fuzzy, $action ) {
143164 if ( $action ) {
144165 return $action;
——@@ -511,7 +532,7 @@
512533 * Prepends translation with fuzzy tag and ensures there is only one of them.
513534 *
514535 * @param $message String: message content
515 - * @return $message \string Message prefixed with TRANSLATE_FUZZY tag
 536+ * @return string Message prefixed with TRANSLATE_FUZZY tag
516537 */
517538 public static function makeTextFuzzy( $message ) {
518539 $message = str_replace( TRANSLATE_FUZZY, '', $message );
Index: trunk/extensions/Translate/utils/StatsTable.php
——@@ -193,7 +193,7 @@
194194 * Gets the name of group linked to translation tool.
195195 * @param $group MessageGroup
196196 * @param $code string Language code
197 - * @param $paras array Any extra query parameters.
 197+ * @param $params array Any extra query parameters.
198198 * @return string Html
199199 */
200200 public function makeGroupLink( MessageGroup $group, $code, $params ) {
Index: trunk/extensions/Translate/utils/StringMatcher.php
——@@ -68,7 +68,7 @@
6969 }
7070
7171 /**
72 - * Cosntructor, see EmptyMatcher();
 72+ * Constructor, see EmptyMatcher();
7373 */
7474 public function __construct( $prefix = '', $patterns = array() ) {
7575 $this->sPrefix = $prefix;
Index: trunk/extensions/Translate/utils/MessageIndex.php
——@@ -73,6 +73,8 @@
7474
7575 /**
7676 * Purge message group stats when set of keys have changed.
 77+ * @param $old array
 78+ * @param $new array
7779 */
7880 protected function clearMessageGroupStats( array $old, array $new ) {
7981 $changes = array();
——@@ -87,6 +89,11 @@
8890 MessageGroupStats::clearGroup( array_keys( $changes ) );
8991 }
9092
 93+ /**
 94+ * @param $hugearray array
 95+ * @param $g
 96+ * @param $ignore bool
 97+ */
9198 protected function checkAndAdd( &$hugearray, $g, $ignore = false ) {
9299 if ( $g instanceof MessageGroupBase ) {
93100 $cache = new MessageGroupCache( $g );
Index: trunk/extensions/Translate/utils/MessageGroupStats.php
——@@ -68,7 +68,7 @@
6969
7070 /**
7171 * Returns stats for all languages in given group.
72 - * @param $code string Group id
 72+ * @param $id string Group id
7373 * @return Array
7474 */
7575 public static function forGroup( $id ) {
——@@ -154,6 +154,7 @@
155155
156156 /**
157157 * Returns an array of needed database fields.
 158+ * @param $row
158159 * @return array
159160 */
160161 protected static function extractNumbers( $row ) {
Index: trunk/extensions/Translate/utils/TranslationHelpers.php
——@@ -194,6 +194,7 @@
195195 * Returns block element HTML snippet that contains the translation aids.
196196 * Not all boxes are shown all the time depending on whether they have
197197 * any information to show and on configuration variables.
 198+ * @param $suggestions string
198199 * @return String. Block level HTML snippet or empty string.
199200 */
200201 public function getBoxes( $suggestions = 'sync' ) {
——@@ -244,7 +245,9 @@
245246
246247 /**
247248 * Returns suggestions from a translation memory.
248 - * @return Html snippet which contains the suggestions.
 249+ * @param $serviceName
 250+ * @param $config
 251+ * @return string Html snippet which contains the suggestions.
249252 */
250253 protected function getTmBox( $serviceName, $config ) {
251254 if ( !$this->targetLanguage ) {
——@@ -1230,7 +1233,9 @@
12311234 }
12321235
12331236 /**
1234 - * Increases the failure count for a given service */
 1237+ * Increases the failure count for a given service
 1238+ * @param $service
 1239+ */
12351240 public static function reportTranslationServiceFailure( $service ) {
12361241 global $wgMemc;
12371242
Index: trunk/extensions/Translate/utils/MessageGroupCache.php
——@@ -68,7 +68,8 @@
6969
7070 /**
7171 * Get an item from the cache.
72 - * @return \string
 72+ * @param $key
 73+ * @return string
7374 */
7475 public function get( $key ) {
7576 return $this->open()->get( $key );
——@@ -225,6 +226,7 @@
226227
227228 /**
228229 * Updates cache to cache format 2.
 230+ * @param $oldcache CdbReader
229231 */
230232 protected function updateCacheFormat( $oldcache ) {
231233 // Read the data from the old format
Index: trunk/extensions/Translate/RcFilter.php
——@@ -64,7 +64,9 @@
6565 * documentation of the function parameters.
6666 *
6767 * Adds a HTMl selector into $items
68 - * @return \bool true
 68+ * @param $items
 69+ * @param $opts
 70+ * @return bool true
6971 */
7072 public static function translationFilterForm( &$items, $opts ) {
7173 $opts->consumeValue( 'translations' );
Index: trunk/extensions/Translate/specials/SpecialManageGroups.php
——@@ -184,6 +184,7 @@
185185 * @todo Very long code block; split up.
186186 *
187187 * @param $group MessageGroup
 188+ * @param $code
188189 */
189190 public function importForm( $group, $code ) {
190191 $this->setSubtitle( $group, $code );
Index: trunk/extensions/Translate/specials/SpecialTranslationStats.php
——@@ -211,7 +211,7 @@
212212
213213 /**
214214 * Constructs a table row with label and radio input in two columns.
215 - * @param $name Option name.
 215+ * @param $name string Option name.
216216 * @param $opts FormOptions
217217 * @param $alts \list{String} List of alternatives.
218218 * @return \string Html.
Index: trunk/extensions/Translate/Groups.php
——@@ -88,6 +88,7 @@
8989 /**
9090 * Initialises a message collection with the given language code,
9191 * message definitions and message tags.
 92+ * @param $code
9293 * @return MessageCollection
9394 */
9495 public function initCollection( $code );
——@@ -97,6 +98,7 @@
9899 * that list may be identical with the translation in the wiki. For other
99100 * groups the messages may be loaded from a file (and differ from the
100101 * current translations or definitions).
 102+ * @param $code
101103 * @return array
102104 */
103105 public function load( $code );
——@@ -104,6 +106,7 @@
105107 /**
106108 * Returns message tags. If type is given, only messages keys with that
107109 * tag is returnted. Otherwise an array[tag => keys] is returnted.
 110+ * @param null $type
108111 * @return array
109112 */
110113 public function getTags( $type = null );
——@@ -112,6 +115,8 @@
113116 * Returns the definition or translation for given message key in given
114117 * language code.
115118 * @todo Is this needed in the interface?
 119+ * @param $key
 120+ * @param $code
116121 * @return string or null
117122 */
118123 public function getMessage( $key, $code );
Index: trunk/extensions/Translate/ffs/MediaWikiComplexMessages.php
——@@ -124,6 +124,7 @@
125125 /**
126126 * Gets data from request. Needs to be run before the form is displayed and
127127 * validation. Not needed for export, which uses request directly.
 128+ * @param $request WebRequest
128129 */
129130 public function loadFromRequest( WebRequest $request ) {
130131 $saved = $this->parse( $this->formatForSave( $request ) );
——@@ -172,6 +173,7 @@
173174
174175 /**
175176 * Return an array of keys that can be used to iterate over all keys
 177+ * @param $group
176178 * @return Array of keys for data
177179 */
178180 protected function getIterator( $group ) {
Index: trunk/extensions/Translate/ffs/Xliff.php
——@@ -35,6 +35,9 @@
3636
3737 /**
3838 * Writes very minimalistic header that validates XLIFF schema.
 39+ * @param $w XMLWriter
 40+ * @param $handle
 41+ * @param $code
3942 */
4043 protected function header( XMLWriter $w, $handle, $code ) {
4144 $w->startDocument( '1.0', 'UTF-8' );
——@@ -61,6 +64,9 @@
6265 /**
6366 * Exports the messages to XLIFF trans-units.
6467 * TODO: Add more information like provided in the web interface.
 68+ * @param $w XMLWriter
 69+ * @param $handle
 70+ * @param $collection MessageCollection
6571 */
6672 protected function messages( XMLWriter $w, $handle, MessageCollection $collection ) {
6773 $w->startElement( 'body' );
——@@ -82,6 +88,9 @@
8389
8490 /**
8591 * Ends the XLIFF document
 92+ * @param $w XMLWriter
 93+ * @param $handle
 94+ * @param $code
8695 */
8796 protected function footer( XMLWriter $w, $handle, $code ) {
8897 $w->endElement(); // </file>

Follow-up revisions

RevisionCommit summaryAuthorDate
r99204* Follow-up r99112: use $user instead of $wgUser....siebrand10:05, 7 October 2011

Comments

#Comment by Nikerabbit (talk | contribs)   17:43, 6 October 2011 
+        * @param null $type

       /**
        * Adds one tests for this checker.
        * @see setChecks()
+        * @param $check
        */
       public function addCheck( $check ) {

I really don't see the point of these types of additions either. It doesn't add anything, but increases code maintenance cost, less code visible on screen etc. 

+ * @param null $channel
#Comment by Reedy (talk | contribs)   18:07, 6 October 2011

I can't see the whitespace issues either in my IDE or just in a text browser, so I'm presuming I've fixed them in a subsequent commit

#Comment by Nikerabbit (talk | contribs)   18:16, 6 October 2011

Whitespace? Should be @param $foo type and not type $foo

Status & tagging log