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

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;

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;

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();

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();

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();

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();

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();

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();

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 ) {

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();

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();

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

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

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
 	 */