From 49efbfe2fb4dd275b7a25a53d507e2aafb136fec Mon Sep 17 00:00:00 2001
From: Umherirrender <umherirrender_de.wp@web.de>
Date: Wed, 28 Oct 2020 21:51:19 +0100
Subject: [PATCH] Improve documentation about object to be stdClass or specific
 type

Some classes still needs exclude for the sniff

Change-Id: I9536c2ee84f6fb4c83cf862a152cf6b00344cb97
---
 .phpcs.xml                                                  | 2 --
 includes/PathRouter.php                                     | 6 +++---
 includes/StubObject.php                                     | 4 ++++
 includes/libs/filebackend/fsfile/TempFSFile.php             | 2 +-
 includes/specialpage/ImageQueryPage.php                     | 2 +-
 includes/specialpage/WantedQueryPage.php                    | 2 +-
 includes/specials/SpecialMostLinkedTemplates.php            | 2 +-
 includes/specials/SpecialNewpages.php                       | 4 ++--
 includes/specials/SpecialProtectedtitles.php                | 2 +-
 tests/phpunit/MediaWikiTestCaseTrait.php                    | 4 ++--
 .../includes/libs/serialization/SerializationTestTrait.php  | 2 ++
 .../includes/libs/serialization/SerializationTestUtils.php  | 5 ++++-
 .../includes/specialpage/FormSpecialPageTestCase.php        | 4 +++-
 tests/phpunit/maintenance/MaintenanceBaseTestCase.php       | 2 +-
 tests/phpunit/unit/includes/FactoryArgTestTrait.php         | 3 +++
 15 files changed, 29 insertions(+), 17 deletions(-)

diff --git a/.phpcs.xml b/.phpcs.xml
index dd1128d0da6..b7d4e3eb43e 100644
--- a/.phpcs.xml
+++ b/.phpcs.xml
@@ -5,8 +5,6 @@
 		<exclude name="MediaWiki.Commenting.FunctionComment.MissingDocumentationPrivate" />
 		<exclude name="MediaWiki.Commenting.FunctionComment.MissingDocumentationProtected" />
 		<exclude name="MediaWiki.Commenting.FunctionComment.MissingDocumentationPublic" />
-		<exclude name="MediaWiki.Commenting.FunctionComment.ObjectTypeHintReturn" />
-		<exclude name="MediaWiki.Commenting.FunctionComment.ObjectTypeHintParam" />
 		<exclude name="MediaWiki.Commenting.PropertyDocumentation.MissingDocumentationPrivate" />
 		<exclude name="MediaWiki.Commenting.PropertyDocumentation.MissingDocumentationProtected" />
 		<exclude name="MediaWiki.Commenting.PropertyDocumentation.MissingDocumentationPublic" />
diff --git a/includes/PathRouter.php b/includes/PathRouter.php
index b0eb5aa5c42..eb88d84a1b0 100644
--- a/includes/PathRouter.php
+++ b/includes/PathRouter.php
@@ -73,7 +73,7 @@
 class PathRouter {
 
 	/**
-	 * @var array
+	 * @var stdClass[]
 	 */
 	private $patterns = [];
 
@@ -209,7 +209,7 @@ class PathRouter {
 	}
 
 	/**
-	 * @param object $pattern
+	 * @param stdClass $pattern
 	 * @return float|int
 	 */
 	protected static function makeWeight( $pattern ) {
@@ -292,7 +292,7 @@ class PathRouter {
 
 	/**
 	 * @param string $path
-	 * @param object $pattern
+	 * @param stdClass $pattern
 	 * @return array|null
 	 */
 	protected static function extractTitle( $path, $pattern ) {
diff --git a/includes/StubObject.php b/includes/StubObject.php
index 1d50b785d30..3b6ece793d9 100644
--- a/includes/StubObject.php
+++ b/includes/StubObject.php
@@ -1,4 +1,8 @@
 <?php
+
+// phpcs:disable MediaWiki.Commenting.FunctionComment.ObjectTypeHintReturn
+// phpcs:disable MediaWiki.Commenting.FunctionComment.ObjectTypeHintParam
+
 /**
  * Delayed loading of global objects.
  *
diff --git a/includes/libs/filebackend/fsfile/TempFSFile.php b/includes/libs/filebackend/fsfile/TempFSFile.php
index 4d6f620c522..86d7ad8f60f 100644
--- a/includes/libs/filebackend/fsfile/TempFSFile.php
+++ b/includes/libs/filebackend/fsfile/TempFSFile.php
@@ -126,7 +126,7 @@ class TempFSFile extends FSFile {
 	/**
 	 * Clean up the temporary file only after an object goes out of scope
 	 *
-	 * @param object $object
+	 * @param mixed $object
 	 * @return TempFSFile This object
 	 */
 	public function bind( $object ) {
diff --git a/includes/specialpage/ImageQueryPage.php b/includes/specialpage/ImageQueryPage.php
index 42c8ac9a17a..df6b9ec55fb 100644
--- a/includes/specialpage/ImageQueryPage.php
+++ b/includes/specialpage/ImageQueryPage.php
@@ -87,7 +87,7 @@ abstract class ImageQueryPage extends QueryPage {
 	 *
 	 * @stable to override
 	 *
-	 * @param object $row Result row
+	 * @param stdClass $row Result row
 	 * @return string
 	 */
 	protected function getCellHtml( $row ) {
diff --git a/includes/specialpage/WantedQueryPage.php b/includes/specialpage/WantedQueryPage.php
index 238432fd10e..7368b82ba9f 100644
--- a/includes/specialpage/WantedQueryPage.php
+++ b/includes/specialpage/WantedQueryPage.php
@@ -114,7 +114,7 @@ abstract class WantedQueryPage extends QueryPage {
 	 * Make a "what links here" link for a given title
 	 *
 	 * @param Title $title Title to make the link for
-	 * @param object $result Result row
+	 * @param stdClass $result Result row
 	 * @return string
 	 */
 	protected function makeWlhLink( $title, $result ) {
diff --git a/includes/specials/SpecialMostLinkedTemplates.php b/includes/specials/SpecialMostLinkedTemplates.php
index 7a1380b98a2..f24cfd1f0c4 100644
--- a/includes/specials/SpecialMostLinkedTemplates.php
+++ b/includes/specials/SpecialMostLinkedTemplates.php
@@ -128,7 +128,7 @@ class SpecialMostLinkedTemplates extends QueryPage {
 	 * Make a "what links here" link for a given title
 	 *
 	 * @param Title $title Title to make the link for
-	 * @param object $result Result row
+	 * @param stdClass $result Result row
 	 * @return string
 	 */
 	private function makeWlhLink( $title, $result ) {
diff --git a/includes/specials/SpecialNewpages.php b/includes/specials/SpecialNewpages.php
index 4518be6c453..e325e12ea6e 100644
--- a/includes/specials/SpecialNewpages.php
+++ b/includes/specials/SpecialNewpages.php
@@ -420,7 +420,7 @@ class SpecialNewpages extends IncludableSpecialPage {
 	 * Format a row, providing the timestamp, links to the page/history,
 	 * size, user links, and a comment
 	 *
-	 * @param object $result Result row
+	 * @param stdClass $result Result row
 	 * @return string
 	 */
 	public function formatRow( $result ) {
@@ -541,7 +541,7 @@ class SpecialNewpages extends IncludableSpecialPage {
 	/**
 	 * Should a specific result row provide "patrollable" links?
 	 *
-	 * @param object $result Result row
+	 * @param stdClass $result Result row
 	 * @return bool
 	 */
 	protected function patrollable( $result ) {
diff --git a/includes/specials/SpecialProtectedtitles.php b/includes/specials/SpecialProtectedtitles.php
index ad8e41c0a34..0425f9f4a6e 100644
--- a/includes/specials/SpecialProtectedtitles.php
+++ b/includes/specials/SpecialProtectedtitles.php
@@ -92,7 +92,7 @@ class SpecialProtectedtitles extends SpecialPage {
 	/**
 	 * Callback function to output a restriction
 	 *
-	 * @param object $row Database row
+	 * @param stdClass $row Database row
 	 * @return string
 	 */
 	public function formatRow( $row ) {
diff --git a/tests/phpunit/MediaWikiTestCaseTrait.php b/tests/phpunit/MediaWikiTestCaseTrait.php
index 405af098484..4571e66512e 100644
--- a/tests/phpunit/MediaWikiTestCaseTrait.php
+++ b/tests/phpunit/MediaWikiTestCaseTrait.php
@@ -34,7 +34,7 @@ trait MediaWikiTestCaseTrait {
 	 * @param string $type
 	 * @param string[] $allow methods to allow
 	 *
-	 * @return object|MockObject
+	 * @return MockObject
 	 */
 	protected function createNoOpMock( $type, $allow = [] ) {
 		$mock = $this->createMock( $type );
@@ -46,7 +46,7 @@ trait MediaWikiTestCaseTrait {
 	 * Return a PHPUnit mock that is expected to never have any methods called on it.
 	 *
 	 * @param string $type
-	 * @return object
+	 * @return MockObject
 	 */
 	protected function createNoOpAbstractMock( $type ) {
 		$mock = $this->getMockBuilder( $type )
diff --git a/tests/phpunit/includes/libs/serialization/SerializationTestTrait.php b/tests/phpunit/includes/libs/serialization/SerializationTestTrait.php
index 5b595be60b8..3f68bc70990 100644
--- a/tests/phpunit/includes/libs/serialization/SerializationTestTrait.php
+++ b/tests/phpunit/includes/libs/serialization/SerializationTestTrait.php
@@ -1,5 +1,7 @@
 <?php
 
+// phpcs:disable MediaWiki.Commenting.FunctionComment.ObjectTypeHintParam
+
 namespace Wikimedia\Tests;
 
 use Generator;
diff --git a/tests/phpunit/includes/libs/serialization/SerializationTestUtils.php b/tests/phpunit/includes/libs/serialization/SerializationTestUtils.php
index 36d03488fad..87d9f71eeaa 100644
--- a/tests/phpunit/includes/libs/serialization/SerializationTestUtils.php
+++ b/tests/phpunit/includes/libs/serialization/SerializationTestUtils.php
@@ -1,4 +1,7 @@
 <?php
+
+// phpcs:disable MediaWiki.Commenting.FunctionComment.ObjectTypeHintReturn
+
 /**
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -195,7 +198,7 @@ class SerializationTestUtils {
 	 * @param string $class
 	 * @param string $testCaseName
 	 * @param string|null $version
-	 * @return object
+	 * @return \stdClass
 	 */
 	public function getStoredSerializedInstance(
 		string $class,
diff --git a/tests/phpunit/includes/specialpage/FormSpecialPageTestCase.php b/tests/phpunit/includes/specialpage/FormSpecialPageTestCase.php
index 5812d68ee42..9ece2c21617 100644
--- a/tests/phpunit/includes/specialpage/FormSpecialPageTestCase.php
+++ b/tests/phpunit/includes/specialpage/FormSpecialPageTestCase.php
@@ -1,5 +1,7 @@
 <?php
 
+// phpcs:disable MediaWiki.Commenting.FunctionComment.ObjectTypeHintParam
+
 use MediaWiki\Block\DatabaseBlock;
 
 /**
@@ -78,7 +80,7 @@ abstract class FormSpecialPageTestCase extends SpecialPageTestBase {
 	 * @param string $name
 	 * @return callable
 	 */
-	protected function getMethod( $obj, $name ) {
+	protected function getMethod( object $obj, $name ) {
 		$method = new ReflectionMethod( $obj, $name );
 		$method->setAccessible( true );
 		return $method->getClosure( $obj );
diff --git a/tests/phpunit/maintenance/MaintenanceBaseTestCase.php b/tests/phpunit/maintenance/MaintenanceBaseTestCase.php
index efee48f3ee2..d5b60374d74 100644
--- a/tests/phpunit/maintenance/MaintenanceBaseTestCase.php
+++ b/tests/phpunit/maintenance/MaintenanceBaseTestCase.php
@@ -57,7 +57,7 @@ abstract class MaintenanceBaseTestCase extends MediaWikiIntegrationTestCase {
 	/**
 	 * Called by setUp to initialize $this->maintenance.
 	 *
-	 * @return object The Maintenance instance to test.
+	 * @return Maintenance The Maintenance instance to test.
 	 */
 	protected function createMaintenance() {
 		$className = $this->getMaintenanceClass();
diff --git a/tests/phpunit/unit/includes/FactoryArgTestTrait.php b/tests/phpunit/unit/includes/FactoryArgTestTrait.php
index b014c29a227..8a586b4f3d7 100644
--- a/tests/phpunit/unit/includes/FactoryArgTestTrait.php
+++ b/tests/phpunit/unit/includes/FactoryArgTestTrait.php
@@ -1,5 +1,8 @@
 <?php
 
+// phpcs:disable MediaWiki.Commenting.FunctionComment.ObjectTypeHintReturn
+// phpcs:disable MediaWiki.Commenting.FunctionComment.ObjectTypeHintParam
+
 /**
  * Test that a factory class correctly forwards all arguments to the class it constructs. This is
  * useful because sometimes a class' constructor will have more arguments added, and it's easy to