fix: Refactor PHPDoc comments for consistency and clarity. (#41)

terabytesoftw · web-flow · commit f9a5422f58ca · 2025-06-14T14:58:08.000-04:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,7 +7,8 @@
 - Enh #37: Enhance `DI` container type inference and testing (@terabytesoftw)
 - Bug #38: Correct exception message formatting in `ServiceMapServiceTest` (@terabytesoftw)
 - Bug #39: Resolve `Container::get()` type inference for unconfigured classes in config (`ServiceMap`) (@terabytesoftw)
-- Enh #40: Enhance `PHPStan` analysis for `Behavior` type inference and testing.
+- Enh #40: Enhance `PHPStan` analysis for `Behavior` type inference and testing (@terabytesoftw)
+- Enh #41: Refactor `PHPDoc` comments for consistency and clarity (@terabytesoftw)
 
 ## 0.2.3 June 09, 2025
 
diff --git a/src/reflection/ApplicationPropertiesClassReflectionExtension.php b/src/reflection/ApplicationPropertiesClassReflectionExtension.php
@@ -19,7 +19,7 @@
 /**
  * Provides property reflection for Yii application components in PHPStan analysis.
  *
- * Integrates Yii's dependency injection and service map with PHPStan's property reflection system, enabling accurate
+ * Integrates Yii's dependency injection and service map with PHPStan property reflection system, enabling accurate
  * type inference and autocompletion for dynamic application components and services.
  *
  * This extension allows PHPStan to recognize properties on the Yii application instance that are defined via
@@ -33,7 +33,7 @@
  *
  * Key features.
  * - Enables accurate type inference for injected services and components.
- * - Ensures compatibility with PHPStan's strict analysis and autocompletion.
+ * - Ensures compatibility with PHPStan strict analysis and autocompletion.
  * - Handles both base and web application contexts.
  * - Integrates annotation-based and native property reflection.
  * - Supports dynamic Yii application properties via service map lookup.
diff --git a/src/reflection/ComponentPropertyReflection.php b/src/reflection/ComponentPropertyReflection.php
@@ -25,7 +25,7 @@
  * Key features.
  * - Accurate type reflection for dynamic Yii application components.
  * - Delegates property behavior to a fallback property reflection instance.
- * - Ensures compatibility with PHPStan's strict analysis and autocompletion.
+ * - Ensures compatibility with PHPStan strict analysis and autocompletion.
  * - Integrates with service-map-based component resolution.
  * - Supports all property visibility and mutability checks.
  *
diff --git a/src/reflection/RequestMethodsClassReflectionExtension.php b/src/reflection/RequestMethodsClassReflectionExtension.php
@@ -27,7 +27,7 @@
  * Key features.
  * - Delegates method reflection to the web request class.
  * - Enables accurate type inference for shared request methods.
- * - Ensures compatibility with PHPStan's strict analysis and autocompletion.
+ * - Ensures compatibility with PHPStan strict analysis and autocompletion.
  * - Handles both console and web request contexts.
  * - Supports dynamic method resolution for console requests.
  *
diff --git a/src/reflection/RequestPropertiesClassReflectionExtension.php b/src/reflection/RequestPropertiesClassReflectionExtension.php
@@ -29,7 +29,7 @@
  * Key features.
  * - Delegates property reflection to the web request class.
  * - Enables accurate type inference for shared request properties.
- * - Ensures compatibility with PHPStan's strict analysis and autocompletion.
+ * - Ensures compatibility with PHPStan strict analysis and autocompletion.
  * - Handles both console and web request contexts.
  * - Supports dynamic property resolution for console requests.
  *
diff --git a/src/reflection/ResponsePropertiesClassReflectionExtension.php b/src/reflection/ResponsePropertiesClassReflectionExtension.php
@@ -29,7 +29,7 @@
  * Key features.
  * - Delegates property reflection to the web response class.
  * - Enables accurate type inference for shared response properties.
- * - Ensures compatibility with PHPStan's strict analysis and autocompletion.
+ * - Ensures compatibility with PHPStan strict analysis and autocompletion.
  * - Handles both console and web response contexts.
  * - Supports dynamic property resolution for console responses.
  *
diff --git a/src/reflection/UserPropertiesClassReflectionExtension.php b/src/reflection/UserPropertiesClassReflectionExtension.php
@@ -32,7 +32,7 @@
  * while providing a custom reflection for the dynamic {@see User::identity] property.
  *
  * Key features.
- * - Ensures compatibility with PHPStan's strict analysis and autocompletion.
+ * - Ensures compatibility with PHPStan strict analysis and autocompletion.
  * - Integrates annotation-based and native property reflection for the user component.
  * - Provides accurate type inference for the dynamic {@see User::identity] property.
  * - Supports dynamic and annotated property resolution for the user component.
diff --git a/src/type/ActiveQueryDynamicMethodReturnTypeExtension.php b/src/type/ActiveQueryDynamicMethodReturnTypeExtension.php
@@ -45,7 +45,7 @@
  * - Dynamic return type inference for {@see ActiveQuery::one()}, {@see ActiveQuery::all()}, and
  *   {@see ActiveQuery::asArray()} methods.
  * - Extraction of model type from generic {@see ActiveQuery} instances.
- * - Integration with PHPStan's type combinators and file type mapper for accurate analysis.
+ * - Integration with PHPStan type combinators and file type mapper for accurate analysis.
  * - Support for union, array, and generic object types in method return values.
  *
  * @see ActiveQuery for query API details.
@@ -80,7 +80,7 @@ public function __construct(
      * Specifies the fully qualified class name of the supported class, enabling PHPStan to associate this extension
      * with method calls on the {@see ActiveQuery} base class and its subclasses.
      *
-     * This method is essential for registering the extension with PHPStan's type system, ensuring that static method
+     * This method is essential for registering the extension with PHPStan type system, ensuring that static method
      * return type inference is applied to the correct class hierarchy during static analysis and IDE autocompletion.
      *
      * @return string Fully qualified class name of the supported {@see ActiveQuery} class.
diff --git a/src/type/ActiveRecordDynamicMethodReturnTypeExtension.php b/src/type/ActiveRecordDynamicMethodReturnTypeExtension.php
@@ -32,7 +32,7 @@
  * Key features.
  * - Accurate return type inference for {@see ActiveRecord::hasOne()} and {@see ActiveRecord::hasMany()} relation
  *   methods.
- * - Compatibility with PHPStan's strict static analysis and autocompletion.
+ * - Compatibility with PHPStan strict static analysis and autocompletion.
  * - Exception handling for invalid or missing arguments in relation method calls.
  * - Returns a generic {@see ActiveQuery} type with the related model class as type parameter.
  *
diff --git a/src/type/ActiveRecordDynamicStaticMethodReturnTypeExtension.php b/src/type/ActiveRecordDynamicStaticMethodReturnTypeExtension.php
@@ -36,7 +36,7 @@
  * The implementation supports:
  * - Accurate return type inference for static ActiveRecord methods returning {@see ThisType}, {@see UnionType},
  *   {@see ActiveQuery}, or custom {@see ActiveQuery} subclasses.
- * - Compatibility with PHPStan's strict static analysis and autocompletion.
+ * - Compatibility with PHPStan strict static analysis and autocompletion.
  * - Model type preservation for generic {@see ActiveQuery} results.
  * - Nullability handling for methods like {@see ActiveRecord::findOne()}.
  * - Support for custom {@see ActiveQuery} subclasses and generic parameter propagation.
@@ -63,7 +63,7 @@ public function __construct(private readonly ReflectionProvider $reflectionProvi
      * Specifies the fully qualified class name of the supported class, enabling PHPStan to associate this extension
      * with static method calls on the {@see ActiveRecord} base class and its subclasses.
      *
-     * This method is essential for registering the extension with PHPStan's type system, ensuring that static method
+     * This method is essential for registering the extension with PHPStan type system, ensuring that static method
      * return type inference is applied to the correct class hierarchy during static analysis and IDE autocompletion.
      *
      * @return string Fully qualified class name of the supported {@see ActiveRecord} class.
diff --git a/src/type/ContainerDynamicMethodReturnTypeExtension.php b/src/type/ContainerDynamicMethodReturnTypeExtension.php
@@ -16,7 +16,7 @@
 /**
  * Provides dynamic return type extension for Yii DI container service resolution in PHPStan analysis.
  *
- * Integrates the Yii dependency injection {@see Container} with PHPStan's dynamic method return type extension system,
+ * Integrates the Yii DI container service {@see Container} with PHPStan dynamic method return type extension system,
  * enabling precise type inference for {@see Container::get()} calls based on service ID and the {@see ServiceMap}.
  *
  * This extension analyzes the first argument of {@see Container::get()} to determine the most accurate return type,
@@ -50,8 +50,8 @@ public function __construct(
     /**
      * Returns the class name for which this dynamic return type extension applies.
      *
-     * Specifies the fully qualified class name of the Yii dependency injection container that this extension targets
-     * for dynamic return type inference in PHPStan analysis.
+     * Specifies the fully qualified class name of the Yii DI container service {@see Container} that this extension
+     * targets for dynamic return type inference in PHPStan analysis.
      *
      * This method enables PHPStan to associate the extension with the {@see Container} class, ensuring that dynamic
      * return type logic is applied to service resolution calls.
@@ -124,8 +124,8 @@ public function getTypeFromMethodCall(
      * Checks if the method name is {@see Container::get}, which is the only method supported by this extension for
      * dynamic return type analysis.
      *
-     * This enables PHPStan to apply custom type inference logic exclusively to service resolution calls on the Yii
-     * dependency injection container.
+     * This enables PHPStan to apply custom type inference logic exclusively to service resolution calls on the Yii DI
+     * container service {@see Container}.
      *
      * @param MethodReflection $methodReflection Reflection instance for the method being analyzed.
      *
diff --git a/src/type/HeaderCollectionDynamicMethodReturnTypeExtension.php b/src/type/HeaderCollectionDynamicMethodReturnTypeExtension.php
@@ -24,7 +24,7 @@
 /**
  * Provides dynamic return type extension for Yii {@see HeaderCollection::get()} method in PHPStan analysis.
  *
- * Integrates Yii's {@see HeaderCollection} dynamic return types with PHPStan's static analysis, enabling accurate type
+ * Integrates Yii's {@see HeaderCollection} dynamic return types with PHPStan static analysis, enabling accurate type
  * inference for the {@see HeaderCollection::get()} method based on the runtime context and method arguments.
  *
  * This extension allows PHPStan to infer the correct return type for the {@see HeaderCollection::get()}` method,
@@ -36,7 +36,7 @@
  *
  * Key features.
  * - Dynamic return type inference for the {@see HeaderCollection::get()} method based on the third argument.
- * - Ensures compatibility with PHPStan's strict analysis and autocompletion.
+ * - Ensures compatibility with PHPStan strict analysis and autocompletion.
  * - Handles runtime context and method argument inspection.
  * - Provides accurate type information for IDEs and static analysis tools.
  * - Supports both string and array result types for header retrieval.
diff --git a/tests/fixture/data/type/ActiveQueryDynamicMethodReturnType.php b/tests/fixture/data/type/ActiveQueryDynamicMethodReturnType.php
@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-namespace yii2\extensions\phpstan\tests\fixture\data\types;
+namespace yii2\extensions\phpstan\tests\fixture\data\type;
 
 use yii\db\{ActiveQuery, ActiveRecord};
 use yii2\extensions\phpstan\tests\stub\MyActiveRecord;
diff --git a/tests/fixture/data/type/ActiveRecordDynamicMethodReturnType.php b/tests/fixture/data/type/ActiveRecordDynamicMethodReturnType.php
@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-namespace yii2\extensions\phpstan\tests\fixture\data\types;
+namespace yii2\extensions\phpstan\tests\fixture\data\type;
 
 use yii\db\{ActiveQuery, ActiveRecord};
 use yii2\extensions\phpstan\tests\stub\{Category, MyActiveRecord, User};
diff --git a/tests/fixture/data/type/ActiveRecordDynamicStaticMethodReturnType.php b/tests/fixture/data/type/ActiveRecordDynamicStaticMethodReturnType.php
@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-namespace yii2\extensions\phpstan\tests\fixture\data\types;
+namespace yii2\extensions\phpstan\tests\fixture\data\type;
 
 use yii\db\{ActiveQuery, ActiveRecord};
 use yii2\extensions\phpstan\tests\stub\{Category, MyActiveRecord, User};
diff --git a/tests/fixture/data/type/ContainerDynamicMethodReturnType.php b/tests/fixture/data/type/ContainerDynamicMethodReturnType.php
@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-namespace yii2\extensions\phpstan\tests\fixture\data\types;
+namespace yii2\extensions\phpstan\tests\fixture\data\type;
 
 use Exception;
 use yii\base\InvalidConfigException;
diff --git a/tests/stub/Category.php b/tests/stub/Category.php
@@ -7,7 +7,7 @@
 use yii\db\ActiveRecord;
 
 /**
- * Category model representing hierarchical category data for testing Active Record scenarios.
+ * Representing hierarchical category data for testing Active Record scenarios.
  *
  * Provides a simple Active Record implementation with integer and string properties, supporting nullable parent
  * relationships for hierarchical data structures.
diff --git a/tests/type/ActiveQueryDynamicReturnTypeExtensionTest.php b/tests/type/ActiveQueryDynamicReturnTypeExtensionTest.php
@@ -37,7 +37,7 @@ public static function dataFileAsserts(): iterable
     {
         $directory = dirname(__DIR__);
 
-        yield from self::gatherAssertTypes("{$directory}/fixture/data/types/ActiveQueryDynamicMethodReturnType.php");
+        yield from self::gatherAssertTypes("{$directory}/fixture/data/type/ActiveQueryDynamicMethodReturnType.php");
     }
 
     public static function getAdditionalConfigFiles(): array
diff --git a/tests/type/ActiveRecordDynamicMethodReturnTypeExtensionTest.php b/tests/type/ActiveRecordDynamicMethodReturnTypeExtensionTest.php
@@ -37,7 +37,7 @@ public static function dataFileAsserts(): iterable
     {
         $directory = dirname(__DIR__);
 
-        yield from self::gatherAssertTypes("{$directory}/fixture/data/types/ActiveRecordDynamicMethodReturnType.php");
+        yield from self::gatherAssertTypes("{$directory}/fixture/data/type/ActiveRecordDynamicMethodReturnType.php");
     }
 
     public static function getAdditionalConfigFiles(): array
diff --git a/tests/type/ActiveRecordDynamicStaticMethodReturnTypeExtensionTest.php b/tests/type/ActiveRecordDynamicStaticMethodReturnTypeExtensionTest.php
@@ -38,7 +38,7 @@ public static function dataFileAsserts(): iterable
         $directory = dirname(__DIR__);
 
         yield from self::gatherAssertTypes(
-            "{$directory}/fixture/data/types/ActiveRecordDynamicStaticMethodReturnType.php",
+            "{$directory}/fixture/data/type/ActiveRecordDynamicStaticMethodReturnType.php",
         );
     }
 
diff --git a/tests/type/ContainerDynamicMethodReturnTypeExtensionTest.php b/tests/type/ContainerDynamicMethodReturnTypeExtensionTest.php
@@ -37,7 +37,7 @@ public static function dataFileAsserts(): iterable
     {
         $directory = dirname(__DIR__);
 
-        yield from self::gatherAssertTypes("{$directory}/fixture/data/types/ContainerDynamicMethodReturnType.php");
+        yield from self::gatherAssertTypes("{$directory}/fixture/data/type/ContainerDynamicMethodReturnType.php");
     }
 
     public static function getAdditionalConfigFiles(): array

Original file line number	Diff line number	Diff line change
`@@ -19,7 +19,7 @@`
`19`	`19`	`/**`
`20`	`20`	`* Provides property reflection for Yii application components in PHPStan analysis.`
`21`	`21`	`*`
`22`		`- * Integrates Yii's dependency injection and service map with PHPStan's property reflection system, enabling accurate`
	`22`	`+ * Integrates Yii's dependency injection and service map with PHPStan property reflection system, enabling accurate`
`23`	`23`	`* type inference and autocompletion for dynamic application components and services.`
`24`	`24`	`*`
`25`	`25`	`* This extension allows PHPStan to recognize properties on the Yii application instance that are defined via`
`@@ -33,7 +33,7 @@`
`33`	`33`	`*`
`34`	`34`	`* Key features.`
`35`	`35`	`* - Enables accurate type inference for injected services and components.`
`36`		`- * - Ensures compatibility with PHPStan's strict analysis and autocompletion.`
	`36`	`+ * - Ensures compatibility with PHPStan strict analysis and autocompletion.`
`37`	`37`	`* - Handles both base and web application contexts.`
`38`	`38`	`* - Integrates annotation-based and native property reflection.`
`39`	`39`	`* - Supports dynamic Yii application properties via service map lookup.`
Original file line number	Diff line number	Diff line change
`@@ -25,7 +25,7 @@`
`25`	`25`	`* Key features.`
`26`	`26`	`* - Accurate type reflection for dynamic Yii application components.`
`27`	`27`	`* - Delegates property behavior to a fallback property reflection instance.`
`28`		`- * - Ensures compatibility with PHPStan's strict analysis and autocompletion.`
	`28`	`+ * - Ensures compatibility with PHPStan strict analysis and autocompletion.`
`29`	`29`	`* - Integrates with service-map-based component resolution.`
`30`	`30`	`* - Supports all property visibility and mutability checks.`
`31`	`31`	`*`
Original file line number	Diff line number	Diff line change
`@@ -27,7 +27,7 @@`
`27`	`27`	`* Key features.`
`28`	`28`	`* - Delegates method reflection to the web request class.`
`29`	`29`	`* - Enables accurate type inference for shared request methods.`
`30`		`- * - Ensures compatibility with PHPStan's strict analysis and autocompletion.`
	`30`	`+ * - Ensures compatibility with PHPStan strict analysis and autocompletion.`
`31`	`31`	`* - Handles both console and web request contexts.`
`32`	`32`	`* - Supports dynamic method resolution for console requests.`
`33`	`33`	`*`
Original file line number	Diff line number	Diff line change
`@@ -29,7 +29,7 @@`
`29`	`29`	`* Key features.`
`30`	`30`	`* - Delegates property reflection to the web request class.`
`31`	`31`	`* - Enables accurate type inference for shared request properties.`
`32`		`- * - Ensures compatibility with PHPStan's strict analysis and autocompletion.`
	`32`	`+ * - Ensures compatibility with PHPStan strict analysis and autocompletion.`
`33`	`33`	`* - Handles both console and web request contexts.`
`34`	`34`	`* - Supports dynamic property resolution for console requests.`
`35`	`35`	`*`
Original file line number	Diff line number	Diff line change
`@@ -32,7 +32,7 @@`
`32`	`32`	`* while providing a custom reflection for the dynamic {@see User::identity] property.`
`33`	`33`	`*`
`34`	`34`	`* Key features.`
`35`		`- * - Ensures compatibility with PHPStan's strict analysis and autocompletion.`
	`35`	`+ * - Ensures compatibility with PHPStan strict analysis and autocompletion.`
`36`	`36`	`* - Integrates annotation-based and native property reflection for the user component.`
`37`	`37`	`* - Provides accurate type inference for the dynamic {@see User::identity] property.`
`38`	`38`	`* - Supports dynamic and annotated property resolution for the user component.`
Original file line number	Diff line number	Diff line change
`@@ -45,7 +45,7 @@`
`45`	`45`	`* - Dynamic return type inference for {@see ActiveQuery::one()}, {@see ActiveQuery::all()}, and`
`46`	`46`	`* {@see ActiveQuery::asArray()} methods.`
`47`	`47`	`* - Extraction of model type from generic {@see ActiveQuery} instances.`
`48`		`- * - Integration with PHPStan's type combinators and file type mapper for accurate analysis.`
	`48`	`+ * - Integration with PHPStan type combinators and file type mapper for accurate analysis.`
`49`	`49`	`* - Support for union, array, and generic object types in method return values.`
`50`	`50`	`*`
`51`	`51`	`* @see ActiveQuery for query API details.`
`@@ -80,7 +80,7 @@ public function __construct(`
`80`	`80`	`* Specifies the fully qualified class name of the supported class, enabling PHPStan to associate this extension`
`81`	`81`	`* with method calls on the {@see ActiveQuery} base class and its subclasses.`
`82`	`82`	`*`
`83`		`- * This method is essential for registering the extension with PHPStan's type system, ensuring that static method`
	`83`	`+ * This method is essential for registering the extension with PHPStan type system, ensuring that static method`
`84`	`84`	`* return type inference is applied to the correct class hierarchy during static analysis and IDE autocompletion.`
`85`	`85`	`*`
`86`	`86`	`* @return string Fully qualified class name of the supported {@see ActiveQuery} class.`