specials: Fix incomplete documentation of execute() param

The parameter passed to the execute() method of each special page can
be null, and usually is. In some of these files this fact was already
mentioned in the comment, but not listed as a type.

In this patch I also remove comments that do not explain much. Saying
that the execute() method of a special page "executes a special page" or
is the "main entry point to a special page" is not super helpful. That's
usually what the documentation in the parent class shoudl explain.
We can add @inheritDoc tags in all these cases if you prefer. Please
tell me.

Change-Id: I1d811ab0c6d5c956e36f6a74120a425abc4332e6

diff --git a/includes/specialpage/ChangesListSpecialPage.php b/includes/specialpage/ChangesListSpecialPage.php
index a8271ac..82bc84d 100644 (file)
--- a/includes/specialpage/ChangesListSpecialPage.php
+++ b/includes/specialpage/ChangesListSpecialPage.php
@@ -616,9 +616,7 @@ abstract class ChangesListSpecialPage extends SpecialPage {
        }
 
        /**
-        * Main execution point
-        *
-        * @param string $subpage
+        * @param string|null $subpage
         */
        public function execute( $subpage ) {
                $this->rcSubpage = $subpage;

diff --git a/includes/specialpage/FormSpecialPage.php b/includes/specialpage/FormSpecialPage.php
index d1c6aea..939460f 100644 (file)
--- a/includes/specialpage/FormSpecialPage.php
+++ b/includes/specialpage/FormSpecialPage.php
@@ -31,7 +31,7 @@
 abstract class FormSpecialPage extends SpecialPage {
        /**
         * The sub-page of the special page.
-        * @var string
+        * @var string|null
         */
        protected $par = null;
 
@@ -166,7 +166,7 @@ abstract class FormSpecialPage extends SpecialPage {
        /**
         * Basic SpecialPage workflow: get a form, send it to the user; get some data back,
         *
-        * @param string $par Subpage string if one was specified
+        * @param string|null $par Subpage string if one was specified
         */
        public function execute( $par ) {
                $this->setParameter( $par );
@@ -188,7 +188,7 @@ abstract class FormSpecialPage extends SpecialPage {
 
        /**
         * Maybe do something interesting with the subpage parameter
-        * @param string $par
+        * @param string|null $par
         */
        protected function setParameter( $par ) {
                $this->par = $par;

diff --git a/includes/specialpage/QueryPage.php b/includes/specialpage/QueryPage.php
index b88479a..f0cb7e5 100644 (file)
--- a/includes/specialpage/QueryPage.php
+++ b/includes/specialpage/QueryPage.php
@@ -578,7 +578,7 @@ abstract class QueryPage extends SpecialPage {
        /**
         * This is the actual workhorse. It does everything needed to make a
         * real, honest-to-gosh query page.
-        * @param string $par
+        * @param string|null $par
         */
        public function execute( $par ) {
                $user = $this->getUser();

diff --git a/includes/specials/SpecialActiveusers.php b/includes/specials/SpecialActiveusers.php
index 0c709af..f52a6f3 100644 (file)
--- a/includes/specials/SpecialActiveusers.php
+++ b/includes/specials/SpecialActiveusers.php
@@ -33,9 +33,7 @@ class SpecialActiveUsers extends SpecialPage {
        }
 
        /**
-        * Show the special page
-        *
-        * @param string $par Parameter passed to the page or null
+        * @param string|null $par Parameter passed to the page or null
         */
        public function execute( $par ) {
                $out = $this->getOutput();

diff --git a/includes/specials/SpecialAllMessages.php b/includes/specials/SpecialAllMessages.php
index 2482d74..878440d 100644 (file)
--- a/includes/specials/SpecialAllMessages.php
+++ b/includes/specials/SpecialAllMessages.php
@@ -35,9 +35,7 @@ class SpecialAllMessages extends SpecialPage {
        }
 
        /**
-        * Show the special page
-        *
-        * @param string $par Parameter passed to the page or null
+        * @param string|null $par Parameter passed to the page or null
         */
        public function execute( $par ) {
                $out = $this->getOutput();

diff --git a/includes/specials/SpecialAutoblockList.php b/includes/specials/SpecialAutoblockList.php
index cab5a2e..34c3371 100644 (file)
--- a/includes/specials/SpecialAutoblockList.php
+++ b/includes/specials/SpecialAutoblockList.php
@@ -34,9 +34,7 @@ class SpecialAutoblockList extends SpecialPage {
        }
 
        /**
-        * Main execution point
-        *
-        * @param string $par Title fragment
+        * @param string|null $par Title fragment
         */
        public function execute( $par ) {
                $this->setHeaders();

diff --git a/includes/specials/SpecialBlockList.php b/includes/specials/SpecialBlockList.php
index 186e5ad..fd27fdc 100644 (file)
--- a/includes/specials/SpecialBlockList.php
+++ b/includes/specials/SpecialBlockList.php
@@ -36,9 +36,7 @@ class SpecialBlockList extends SpecialPage {
        }
 
        /**
-        * Main execution point
-        *
-        * @param string $par Title fragment
+        * @param string|null $par Title fragment
         */
        public function execute( $par ) {
                $this->setHeaders();

diff --git a/includes/specials/SpecialBooksources.php b/includes/specials/SpecialBooksources.php
index 2fe38ed..ea9ddaf 100644 (file)
--- a/includes/specials/SpecialBooksources.php
+++ b/includes/specials/SpecialBooksources.php
@@ -36,9 +36,7 @@ class SpecialBookSources extends SpecialPage {
        }
 
        /**
-        * Show the special page
-        *
-        * @param string $isbn ISBN passed as a subpage parameter
+        * @param string|null $isbn ISBN passed as a subpage parameter
         */
        public function execute( $isbn ) {
                $out = $this->getOutput();

diff --git a/includes/specials/SpecialComparePages.php b/includes/specials/SpecialComparePages.php
index d6fb10f..9d1b79e 100644 (file)
--- a/includes/specials/SpecialComparePages.php
+++ b/includes/specials/SpecialComparePages.php
@@ -43,7 +43,7 @@ class SpecialComparePages extends SpecialPage {
        /**
         * Show a form for filtering namespace and username
         *
-        * @param string $par
+        * @param string|null $par
         * @return string
         */
        public function execute( $par ) {

diff --git a/includes/specials/SpecialListusers.php b/includes/specials/SpecialListusers.php
index 2c35815..7aef4ae 100644 (file)
--- a/includes/specials/SpecialListusers.php
+++ b/includes/specials/SpecialListusers.php
@@ -35,9 +35,7 @@ class SpecialListUsers extends IncludableSpecialPage {
        }
 
        /**
-        * Show the special page
-        *
-        * @param string $par (optional) A group to list users from
+        * @param string|null $par (optional) A group to list users from
         */
        public function execute( $par ) {
                $this->setHeaders();

diff --git a/includes/specials/SpecialNewpages.php b/includes/specials/SpecialNewpages.php
index 1f81cf0..1b8ba85 100644 (file)
--- a/includes/specials/SpecialNewpages.php
+++ b/includes/specials/SpecialNewpages.php
@@ -39,6 +39,9 @@ class SpecialNewpages extends IncludableSpecialPage {
                parent::__construct( 'Newpages' );
        }
 
+       /**
+        * @param string|null $par
+        */
        protected function setup( $par ) {
                $opts = new FormOptions();
                $this->opts = $opts; // bind
@@ -70,6 +73,9 @@ class SpecialNewpages extends IncludableSpecialPage {
                $opts->validateIntBounds( 'limit', 0, 5000 );
        }
 
+       /**
+        * @param string $par
+        */
        protected function parseParams( $par ) {
                $bits = preg_split( '/\s*,\s*/', trim( $par ) );
                foreach ( $bits as $bit ) {
@@ -115,7 +121,7 @@ class SpecialNewpages extends IncludableSpecialPage {
        /**
         * Show a form for filtering namespace and username
         *
-        * @param string $par
+        * @param string|null $par
         */
        public function execute( $par ) {
                $out = $this->getOutput();

diff --git a/includes/specials/SpecialRecentchanges.php b/includes/specials/SpecialRecentchanges.php
index 46b5520..c8f65c1 100644 (file)
--- a/includes/specials/SpecialRecentchanges.php
+++ b/includes/specials/SpecialRecentchanges.php
@@ -136,9 +136,7 @@ class SpecialRecentChanges extends ChangesListSpecialPage {
        }
 
        /**
-        * Main execution point
-        *
-        * @param string $subpage
+        * @param string|null $subpage
         */
        public function execute( $subpage ) {
                // Backwards-compatibility: redirect to new feed URLs

diff --git a/includes/specials/SpecialUpload.php b/includes/specials/SpecialUpload.php
index dbb1481..5a1b8fb 100644 (file)
--- a/includes/specials/SpecialUpload.php
+++ b/includes/specials/SpecialUpload.php
@@ -146,8 +146,7 @@ class SpecialUpload extends SpecialPage {
        }
 
        /**
-        * Special page entry point
-        * @param string $par
+        * @param string|null $par
         * @throws ErrorPageError
         * @throws Exception
         * @throws FatalError

diff --git a/includes/specials/SpecialUploadStash.php b/includes/specials/SpecialUploadStash.php
index 4d0c20c..fe55d94 100644 (file)
--- a/includes/specials/SpecialUploadStash.php
+++ b/includes/specials/SpecialUploadStash.php
@@ -60,7 +60,7 @@ class SpecialUploadStash extends UnlistedSpecialPage {
        /**
         * Execute page -- can output a file directly or show a listing of them.
         *
-        * @param string $subPage Subpage, e.g. in
+        * @param string|null $subPage Subpage, e.g. in
         *   https://example.com/wiki/Special:UploadStash/foo.jpg, the "foo.jpg" part
         * @return bool Success
         */