specials: Cleanup and fix PHPDoc comments

Fix and cleanup code documentation in PHPDoc for clarity. This involves
correcting return types, parameter types and errors expected to be thrown
by methods within a class.

Change-Id: I30ba4b99d25460f84d348dd96480df67e92c69a6

diff --git a/includes/specials/SpecialAllPages.php b/includes/specials/SpecialAllPages.php
index e96df0b..fc32d2d 100644 (file)
--- a/includes/specials/SpecialAllPages.php
+++ b/includes/specials/SpecialAllPages.php
@@ -169,8 +169,8 @@ class SpecialAllPages extends IncludableSpecialPage {
 
        /**
         * @param int $namespace Namespace (Default NS_MAIN)
 
        /**
         * @param int $namespace Namespace (Default NS_MAIN)

-        * @param string $from List all pages from this name (default false)
-        * @param string $to List all pages to this name (default false)
+        * @param string|false $from List all pages from this name (default false)
+        * @param string|false $to List all pages to this name (default false)

         * @param bool $hideredirects Don't show redirects (default false)
         */
        function showChunk( $namespace = NS_MAIN, $from = false, $to = false, $hideredirects = false ) {
         * @param bool $hideredirects Don't show redirects (default false)
         */
        function showChunk( $namespace = NS_MAIN, $from = false, $to = false, $hideredirects = false ) {

diff --git a/includes/specials/SpecialBlock.php b/includes/specials/SpecialBlock.php
index a00c42c..a816edc 100644 (file)
--- a/includes/specials/SpecialBlock.php
+++ b/includes/specials/SpecialBlock.php
@@ -310,8 +310,6 @@ class SpecialBlock extends FormSpecialPage {
         * If the user has already been blocked with similar settings, load that block
         * and change the defaults for the form fields to match the existing settings.
         * @param array &$fields HTMLForm descriptor array
         * If the user has already been blocked with similar settings, load that block
         * and change the defaults for the form fields to match the existing settings.
         * @param array &$fields HTMLForm descriptor array

-        * @return bool Whether fields were altered (that is, whether the target is
-        *     already blocked)

         */
        protected function maybeAlterFormDefaults( &$fields ) {
                # This will be overwritten by request data
         */
        protected function maybeAlterFormDefaults( &$fields ) {
                # This will be overwritten by request data

diff --git a/includes/specials/SpecialEditTags.php b/includes/specials/SpecialEditTags.php
index 02b72dd..bcc81c7 100644 (file)
--- a/includes/specials/SpecialEditTags.php
+++ b/includes/specials/SpecialEditTags.php
@@ -374,7 +374,6 @@ class SpecialEditTags extends UnlistedSpecialPage {
 
        /**
         * UI entry point for form submission.
 
        /**
         * UI entry point for form submission.

-        * @throws PermissionsError

         * @return bool
         */
        protected function submit() {
         * @return bool
         */
        protected function submit() {

diff --git a/includes/specials/SpecialLinkAccounts.php b/includes/specials/SpecialLinkAccounts.php
index d4ef936..859a638 100644 (file)
--- a/includes/specials/SpecialLinkAccounts.php
+++ b/includes/specials/SpecialLinkAccounts.php
@@ -32,8 +32,8 @@ class SpecialLinkAccounts extends AuthManagerSpecialPage {
 
        /**
         * @param null|string $subPage
 
        /**
         * @param null|string $subPage

-        * @throws MWException
-        * @throws PermissionsError
+        * @throws ErrorPageError
+        * @throws LogicException

         */
        public function execute( $subPage ) {
                $this->setHeaders();
         */
        public function execute( $subPage ) {
                $this->setHeaders();

diff --git a/includes/specials/SpecialLog.php b/includes/specials/SpecialLog.php
index 594626f..4d50642 100644 (file)
--- a/includes/specials/SpecialLog.php
+++ b/includes/specials/SpecialLog.php
@@ -180,7 +180,6 @@ class SpecialLog extends SpecialPage {
         *
         * @param FormOptions $opts
         * @param string $par
         *
         * @param FormOptions $opts
         * @param string $par

-        * @throws ConfigException

         */
        private function parseParams( FormOptions $opts, $par ) {
                # Get parameters
         */
        private function parseParams( FormOptions $opts, $par ) {
                # Get parameters

diff --git a/includes/specials/SpecialRandomInCategory.php b/includes/specials/SpecialRandomInCategory.php
index adf12d4..d781e16 100644 (file)
--- a/includes/specials/SpecialRandomInCategory.php
+++ b/includes/specials/SpecialRandomInCategory.php
@@ -291,7 +291,7 @@ class SpecialRandomInCategory extends FormSpecialPage {
         * @param int $offset A small offset to make the result seem more "random"
         * @param bool $up Get the result above the random value
         * @param string $fname The name of the calling method
         * @param int $offset A small offset to make the result seem more "random"
         * @param bool $up Get the result above the random value
         * @param string $fname The name of the calling method

-        * @return array Info for the title selected.
+        * @return stdClass|false Info for the title selected.

         */
        private function selectRandomPageFromDB( $rand, $offset, $up, $fname = __METHOD__ ) {
                $dbr = wfGetDB( DB_REPLICA );
         */
        private function selectRandomPageFromDB( $rand, $offset, $up, $fname = __METHOD__ ) {
                $dbr = wfGetDB( DB_REPLICA );

diff --git a/includes/specials/SpecialRecentchanges.php b/includes/specials/SpecialRecentchanges.php
index b566305..1e016a5 100644 (file)
--- a/includes/specials/SpecialRecentchanges.php
+++ b/includes/specials/SpecialRecentchanges.php
@@ -674,7 +674,7 @@ class SpecialRecentChanges extends ChangesListSpecialPage {
         * Creates the choose namespace selection
         *
         * @param FormOptions $opts
         * Creates the choose namespace selection
         *
         * @param FormOptions $opts

-        * @return string
+        * @return string[]

         */
        protected function namespaceFilterForm( FormOptions $opts ) {
                $nsSelect = Html::namespaceSelector(
         */
        protected function namespaceFilterForm( FormOptions $opts ) {
                $nsSelect = Html::namespaceSelector(

diff --git a/includes/specials/SpecialUploadStash.php b/includes/specials/SpecialUploadStash.php
index 2da9a41..abd3e07 100644 (file)
--- a/includes/specials/SpecialUploadStash.php
+++ b/includes/specials/SpecialUploadStash.php
@@ -165,8 +165,6 @@ class SpecialUploadStash extends UnlistedSpecialPage {
         *
         * @param File $file
         * @param array $params
         *
         * @param File $file
         * @param array $params

-        *
-        * @return bool Success

         */
        private function outputThumbFromStash( $file, $params ) {
                $flags = 0;
         */
        private function outputThumbFromStash( $file, $params ) {
                $flags = 0;

diff --git a/includes/specials/pagers/AllMessagesTablePager.php b/includes/specials/pagers/AllMessagesTablePager.php
index 8081f4d..f045333 100644 (file)
--- a/includes/specials/pagers/AllMessagesTablePager.php
+++ b/includes/specials/pagers/AllMessagesTablePager.php
@@ -281,7 +281,10 @@ class AllMessagesTablePager extends TablePager {
                return '';
        }
 
                return '';
        }
 

-       /** @return string HTML */
+       /**
+        * @param stdClass $row
+        * @return string HTML
+        */

        function formatRow( $row ) {
                // Do all the normal stuff
                $s = parent::formatRow( $row );
        function formatRow( $row ) {
                // Do all the normal stuff
                $s = parent::formatRow( $row );


@@ -306,7 +309,11 @@ class AllMessagesTablePager extends TablePager {
                return [];
        }
 
                return [];
        }
 

-       /** @return array HTML attributes */
+       /**
+        * @param string $field
+        * @param string $value
+        * @return array HTML attributes
+        */

        function getCellAttrs( $field, $value ) {
                $attr = [];
                if ( $field === 'am_title' ) {
        function getCellAttrs( $field, $value ) {
                $attr = [];
                if ( $field === 'am_title' ) {