Add property documentation

umherirrender · umherirrender · commit 547a34992532 · 2025-02-17T23:07:43.000+01:00
Disable sniff for function documentation

Change-Id: Ife99c527afc09ad016f8a2af928904702b095e6f
diff --git a/.phpcs.xml b/.phpcs.xml
@@ -1,11 +1,18 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <ruleset>
 	<rule ref="./vendor/mediawiki/mediawiki-codesniffer/MediaWiki">
-		<exclude name="MediaWiki.Commenting.FunctionComment.MissingDocumentationPublic" />
-		<exclude name="MediaWiki.Commenting.PropertyDocumentation.MissingDocumentationPrivate" />
-		<exclude name="MediaWiki.Commenting.PropertyDocumentation.MissingVar" />
 		<exclude name="MediaWiki.WhiteSpace.SpaceBeforeSingleLineComment.NewLineComment" />
 	</rule>
+	<!--
+	  - It's generally incorrect to add doc comments to overridden methods.
+	  - Use of @inheritDoc or any other such text breaks Doxygen's automatic
+	  - documentation inheritance.
+	  - For methods that are not overriding something, this rule is correct,
+	  - but there is apparently no way to select only those methods.
+	  -->
+	<rule ref="MediaWiki.Commenting.FunctionComment.MissingDocumentationPublic">
+		<severity>0</severity>
+	</rule>
 	<rule ref="Generic.PHP.NoSilencedErrors.Discouraged">
 		<exclude-pattern>*/tests/*</exclude-pattern>
 	</rule>
diff --git a/src/Reader/DBA.php b/src/Reader/DBA.php
@@ -30,7 +30,7 @@ class DBA extends Reader {
 	 */
 	protected $handle;
 
-	public function __construct( $fileName ) {
+	public function __construct( string $fileName ) {
 		$this->handle = dba_open( $fileName, 'r-', 'cdb' );
 		if ( !$this->handle ) {
 			throw new Exception( 'Unable to open CDB file "' . $fileName . '"' );
diff --git a/src/Reader/PHP.php b/src/Reader/PHP.php
@@ -36,7 +36,7 @@ class PHP extends Reader {
 	protected $fileName;
 
 	/**
-	 * The file handle
+	 * @var resource|false|null The file handle
 	 */
 	protected $handle;
 
diff --git a/src/Writer/DBA.php b/src/Writer/DBA.php
@@ -26,7 +26,7 @@
  */
 class DBA extends Writer {
 	/**
-	 * The file handle
+	 * @var resource|false|null The file handle
 	 */
 	protected $handle;
 
diff --git a/tests/CdbTest.php b/tests/CdbTest.php
@@ -14,8 +14,8 @@
  * @covers \Cdb\Reader\DBA
  */
 class CdbTest extends TestCase {
-	private $phpCdbFile;
-	private $dbaCdbFile;
+	private string $phpCdbFile;
+	private string $dbaCdbFile;
 
 	protected function setUp(): void {
 		parent::setUp();
diff --git a/tests/CliTest.php b/tests/CliTest.php
@@ -9,6 +9,7 @@
  */
 class CliTest extends TestCase {
 	private const FIXTURE = __DIR__ . '/fixture/example.cdb';
+	/** @var resource|null */
 	private $out;
 
 	protected function setUp(): void {
diff --git a/tests/Reader/PHPTest.php b/tests/Reader/PHPTest.php
@@ -9,7 +9,7 @@
  * @covers \Cdb\Reader\PHP
  */
 class PHPTest extends TestCase {
-	private $cdbFile;
+	private string $cdbFile;
 
 	protected function setUp(): void {
 		parent::setUp();
