r112252 MediaWiki - Code Review archive

Repository:MediaWiki
Revision:r112251‎ | r112252 | r112253 >
Date:22:26, 23 February 2012
Author:jeroendedauw
Status:ok (Comments)
Tags:
Comment:
docs++
Modified paths:
  • /trunk/phase3/includes/Pager.php (modified) (history)

Diff [purge]

Index: trunk/phase3/includes/Pager.php
@@ -837,7 +837,7 @@
838838 var $mSort;
839839 var $mCurrentRow;
840840
841 - function __construct( IContextSource $context = null ) {
 841+ public function __construct( IContextSource $context = null ) {
842842 if ( $context ) {
843843 $this->setContext( $context );
844844 }
@@ -855,6 +855,10 @@
856856 parent::__construct();
857857 }
858858
 859+ /**
 860+ * @protected
 861+ * @return string
 862+ */
859863 function getStartBody() {
860864 global $wgStylePath;
861865 $tableClass = htmlspecialchars( $this->getTableClass() );
@@ -901,10 +905,18 @@
902906 return $s;
903907 }
904908
 909+ /**
 910+ * @protected
 911+ * @return string
 912+ */
905913 function getEndBody() {
906914 return "</tbody></table>\n";
907915 }
908916
 917+ /**
 918+ * @protected
 919+ * @return string
 920+ */
909921 function getEmptyBody() {
910922 $colspan = count( $this->getFieldNames() );
911923 $msgEmpty = wfMsgHtml( 'table_pager_empty' );
@@ -912,6 +924,7 @@
913925 }
914926
915927 /**
 928+ * @protected
916929 * @param $row Array
917930 * @return String HTML
918931 */
@@ -934,6 +947,8 @@
935948 /**
936949 * Get a class name to be applied to the given row.
937950 *
 951+ * @protected
 952+ *
938953 * @param $row Object: the database result row
939954 * @return String
940955 */
@@ -944,6 +959,8 @@
945960 /**
946961 * Get attributes to be applied to the given row.
947962 *
 963+ * @protected
 964+ *
948965 * @param $row Object: the database result row
949966 * @return Array of <attr> => <value>
950967 */
@@ -962,6 +979,8 @@
963980 * take this as an excuse to hardcode styles; use classes and
964981 * CSS instead. Row context is available in $this->mCurrentRow
965982 *
 983+ * @protected
 984+ *
966985 * @param $field String The column
967986 * @param $value String The cell contents
968987 * @return Array of attr => value
@@ -970,18 +989,34 @@
971990 return array( 'class' => 'TablePager_col_' . $field );
972991 }
973992
 993+ /**
 994+ * @protected
 995+ * @return string
 996+ */
974997 function getIndexField() {
975998 return $this->mSort;
976999 }
9771000
 1001+ /**
 1002+ * @protected
 1003+ * @return string
 1004+ */
9781005 function getTableClass() {
9791006 return 'TablePager';
9801007 }
9811008
 1009+ /**
 1010+ * @protected
 1011+ * @return string
 1012+ */
9821013 function getNavClass() {
9831014 return 'TablePager_nav';
9841015 }
9851016
 1017+ /**
 1018+ * @protected
 1019+ * @return string
 1020+ */
9861021 function getSortHeaderClass() {
9871022 return 'TablePager_sort';
9881023 }
@@ -990,7 +1025,7 @@
9911026 * A navigation bar with images
9921027 * @return String HTML
9931028 */
994 - function getNavigationBar() {
 1029+ public function getNavigationBar() {
9951030 global $wgStylePath;
9961031
9971032 if ( !$this->isNavigationBarShown() ) {
@@ -1046,7 +1081,7 @@
10471082 *
10481083 * @return String: HTML fragment
10491084 */
1050 - function getLimitSelect() {
 1085+ public function getLimitSelect() {
10511086 # Add the current limit from the query string
10521087 # to avoid that the limit is lost after clicking Go next time
10531088 if ( !in_array( $this->mLimit, $this->mLimitsShown ) ) {
@@ -1139,13 +1174,19 @@
11401175 * The current result row is available as $this->mCurrentRow, in case you
11411176 * need more context.
11421177 *
 1178+ * @protected
 1179+ *
11431180 * @param $name String: the database field name
11441181 * @param $value String: the value retrieved from the database
11451182 */
11461183 abstract function formatValue( $name, $value );
11471184
11481185 /**
1149 - * The database field name used as a default sort order
 1186+ * The database field name used as a default sort order.
 1187+ *
 1188+ * @protected
 1189+ *
 1190+ * @return string
11501191 */
11511192 abstract function getDefaultSort();
11521193

Comments

#Comment by Aaron Schulz (talk | contribs)   22:41, 23 February 2012

I guess this is for b/c but we almost always avoid visibility documentation and just actually make the thing protected or private.

#Comment by Jeroen De Dauw (talk | contribs)   00:40, 24 February 2012

Almost always? I seriously hope no one just documents it's visibility and not actually enforces it for new code o_O

Yeah, this is for b/c. It so sucks that you can not change the visibility of a method without forcing all subclasses overriding it to also change it, and there is no way to "migrate" next to introducing a method with different name, which ofc sucks :/

Status & tagging log