More rich PHPDocs for extension interfaces

phpstan · Mar 24, 2023 · f67a372 · f67a372
1 parent 23d29ab
commit f67a372
Show file tree

Hide file tree

Showing 19 changed files with 323 additions and 18 deletions.
diff --git a/src/Collectors/Collector.php b/src/Collectors/Collector.php
@@ -6,6 +6,19 @@
 use PHPStan\Analyser\Scope;
 
 /**
+ * This is the interface custom collectors implement. To register it in the configuration file
+ * use the `phpstan.collector` service tag:
+ *
+ * ```
+ * services:
+ * 	-
+ *		class: App\MyCollector
+ *		tags:
+ *			- phpstan.collector
+ * ```
+ *
+ * Learn more: https://phpstan.org/developing-extensions/collectors
+ *
  * @api
  * @phpstan-template-covariant TNodeType of Node
  * @phpstan-template-covariant TValue

diff --git a/src/Command/ErrorFormatter/ErrorFormatter.php b/src/Command/ErrorFormatter/ErrorFormatter.php
@@ -5,7 +5,20 @@
 use PHPStan\Command\AnalysisResult;
 use PHPStan\Command\Output;
 
-/** @api */
+/**
+ * This is the interface custom error formatters implement. Register it in the configuration file
+ * like this:
+ *
+ * ```
+ * services:
+ * 	errorFormatter.myFormat:
+ *		class: App\PHPStan\AwesomeErrorFormatter
+ * ```
+ *
+ * Learn more: https://phpstan.org/developing-extensions/error-formatters
+ *
+ * @api
+ */
 interface ErrorFormatter
 {
 

diff --git a/src/PhpDoc/StubFilesExtension.php b/src/PhpDoc/StubFilesExtension.php
@@ -2,7 +2,24 @@
 
 namespace PHPStan\PhpDoc;
 
-/** @api */
+/**
+ * This is the extension interface to implement if you want to dynamically
+ * load stub files based on your logic. As opposed to simply list them in the configuration file.
+ *
+ * To register it in the configuration file use the `phpstan.stubFilesExtension` service tag:
+ *
+ * ```
+ * services:
+ * 	-
+ *		class: App\PHPStan\MyExtension
+ *		tags:
+ *			- phpstan.stubFilesExtension
+ * ```
+ *
+ * Learn more: https://phpstan.org/developing-extensions/allowed-subtypes
+ *
+ * @api
+ */
 interface StubFilesExtension
 {
 

diff --git a/src/PhpDoc/TypeNodeResolverExtension.php b/src/PhpDoc/TypeNodeResolverExtension.php
@@ -6,7 +6,23 @@
 use PHPStan\PhpDocParser\Ast\Type\TypeNode;
 use PHPStan\Type\Type;
 
-/** @api */
+/**
+ * This is the interface type node resolver extensions implement for custom PHPDoc types.
+ *
+ * To register it in the configuration file use the `phpstan.phpDoc.typeNodeResolverExtension` service tag:
+ *
+ * ```
+ * services:
+ * 	-
+ *		class: App\PHPStan\MyExtension
+ *		tags:
+ *			- phpstan.phpDoc.typeNodeResolverExtension
+ * ```
+ *
+ * Learn more: https://phpstan.org/developing-extensions/custom-phpdoc-types
+ *
+ * @api
+ */
 interface TypeNodeResolverExtension
 {
 

diff --git a/src/Reflection/AllowedSubTypesClassReflectionExtension.php b/src/Reflection/AllowedSubTypesClassReflectionExtension.php
@@ -4,7 +4,25 @@
 
 use PHPStan\Type\Type;
 
-/** @api */
+/**
+ * This is the extension interface to implement if you want to described
+ * allowed subtypes - to limit which classes can implement a certain interface
+ * or extend a certain parent class.
+ *
+ * To register it in the configuration file use the `phpstan.broker.allowedSubTypesClassReflectionExtension` service tag:
+ *
+ * ```
+ * services:
+ * 	-
+ *		class: App\PHPStan\MyExtension
+ *		tags:
+ *			- phpstan.broker.allowedSubTypesClassReflectionExtension
+ * ```
+ *
+ * Learn more: https://phpstan.org/developing-extensions/allowed-subtypes
+ *
+ * @api
+ */
 interface AllowedSubTypesClassReflectionExtension
 {
 

diff --git a/src/Reflection/MethodsClassReflectionExtension.php b/src/Reflection/MethodsClassReflectionExtension.php
@@ -2,7 +2,23 @@
 
 namespace PHPStan\Reflection;
 
-/** @api */
+/**
+ * This is the interface custom methods class reflection extensions implement.
+ *
+ * To register it in the configuration file use the `phpstan.broker.methodsClassReflectionExtension` service tag:
+ *
+ * ```
+ * services:
+ * 	-
+ *		class: App\PHPStan\MyMethodsClassReflectionExtension
+ *		tags:
+ *			- phpstan.broker.methodsClassReflectionExtension
+ * ```
+ *
+ * Learn more: https://phpstan.org/developing-extensions/class-reflection-extensions
+ *
+ * @api
+ */
 interface MethodsClassReflectionExtension
 {
 

diff --git a/src/Reflection/PropertiesClassReflectionExtension.php b/src/Reflection/PropertiesClassReflectionExtension.php
@@ -2,7 +2,23 @@
 
 namespace PHPStan\Reflection;
 
-/** @api */
+/**
+ * This is the interface custom properties class reflection extensions implement.
+ *
+ * To register it in the configuration file use the `phpstan.broker.propertiesClassReflectionExtension` service tag:
+ *
+ * ```
+ * services:
+ * 	-
+ *		class: App\PHPStan\MyPropertiesClassReflectionExtension
+ *		tags:
+ *			- phpstan.broker.propertiesClassReflectionExtension
+ * ```
+ *
+ * Learn more: https://phpstan.org/developing-extensions/class-reflection-extensions
+ *
+ * @api
+ */
 interface PropertiesClassReflectionExtension
 {
 

diff --git a/src/Rules/Constants/AlwaysUsedClassConstantsExtension.php b/src/Rules/Constants/AlwaysUsedClassConstantsExtension.php
@@ -4,7 +4,24 @@
 
 use PHPStan\Reflection\ConstantReflection;
 
-/** @api */
+/**
+ * This is the extension interface to implement if you want to describe
+ * always-used class constant.
+ *
+ * To register it in the configuration file use the `phpstan.constants.alwaysUsedClassConstantsExtension` service tag:
+ *
+ * ```
+ * services:
+ * 	-
+ *		class: App\PHPStan\MyExtension
+ *		tags:
+ *			- phpstan.constants.alwaysUsedClassConstantsExtension
+ * ```
+ *
+ * Learn more: https://phpstan.org/developing-extensions/always-used-class-constants
+ *
+ * @api
+ */
 interface AlwaysUsedClassConstantsExtension
 {
 

diff --git a/src/Rules/Properties/ReadWritePropertiesExtension.php b/src/Rules/Properties/ReadWritePropertiesExtension.php
@@ -4,7 +4,24 @@
 
 use PHPStan\Reflection\PropertyReflection;
 
-/** @api */
+/**
+ * This is the extension interface to implement if you want to describe
+ * always-read or always-written properties.
+ *
+ * To register it in the configuration file use the `phpstan.properties.readWriteExtension` service tag:
+ *
+ * ```
+ * services:
+ * 	-
+ *		class: App\PHPStan\MyExtension
+ *		tags:
+ *			- phpstan.properties.readWriteExtension
+ * ```
+ *
+ * Learn more: https://phpstan.org/developing-extensions/always-read-written-properties
+ *
+ * @api
+ */
 interface ReadWritePropertiesExtension
 {
 

diff --git a/src/Type/DynamicFunctionReturnTypeExtension.php b/src/Type/DynamicFunctionReturnTypeExtension.php
@@ -6,7 +6,23 @@
 use PHPStan\Analyser\Scope;
 use PHPStan\Reflection\FunctionReflection;
 
-/** @api */
+/**
+ * This is the interface dynamic return type extensions implement for functions.
+ *
+ * To register it in the configuration file use the `phpstan.broker.dynamicFunctionReturnTypeExtension` service tag:
+ *
+ * ```
+ * services:
+ * 	-
+ *		class: App\PHPStan\MyExtension
+ *		tags:
+ *			- phpstan.broker.dynamicFunctionReturnTypeExtension
+ * ```
+ *
+ * Learn more: https://phpstan.org/developing-extensions/dynamic-return-type-extensions
+ *
+ * @api
+ */
 interface DynamicFunctionReturnTypeExtension
 {
 

diff --git a/src/Type/DynamicFunctionThrowTypeExtension.php b/src/Type/DynamicFunctionThrowTypeExtension.php
@@ -6,7 +6,23 @@
 use PHPStan\Analyser\Scope;
 use PHPStan\Reflection\FunctionReflection;
 
-/** @api */
+/**
+ * This is the interface dynamic throw type extensions implement for functions.
+ *
+ * To register it in the configuration file use the `phpstan.dynamicFunctionThrowTypeExtension` service tag:
+ *
+ * ```
+ * services:
+ * 	-
+ *		class: App\PHPStan\MyExtension
+ *		tags:
+ *			- phpstan.dynamicFunctionThrowTypeExtension
+ * ```
+ *
+ * Learn more: https://phpstan.org/developing-extensions/dynamic-throw-type-extensions
+ *
+ * @api
+ */
 interface DynamicFunctionThrowTypeExtension
 {
 

diff --git a/src/Type/DynamicMethodReturnTypeExtension.php b/src/Type/DynamicMethodReturnTypeExtension.php
@@ -6,7 +6,23 @@
 use PHPStan\Analyser\Scope;
 use PHPStan\Reflection\MethodReflection;
 
-/** @api */
+/**
+ * This is the interface dynamic return type extensions implement for non-static methods.
+ *
+ * To register it in the configuration file use the `phpstan.broker.dynamicMethodReturnTypeExtension` service tag:
+ *
+ * ```
+ * services:
+ * 	-
+ *		class: App\PHPStan\MyExtension
+ *		tags:
+ *			- phpstan.broker.dynamicMethodReturnTypeExtension
+ * ```
+ *
+ * Learn more: https://phpstan.org/developing-extensions/dynamic-return-type-extensions
+ *
+ * @api
+ */
 interface DynamicMethodReturnTypeExtension
 {
 

diff --git a/src/Type/DynamicMethodThrowTypeExtension.php b/src/Type/DynamicMethodThrowTypeExtension.php
@@ -6,7 +6,23 @@
 use PHPStan\Analyser\Scope;
 use PHPStan\Reflection\MethodReflection;
 
-/** @api */
+/**
+ * This is the interface dynamic throw type extensions implement for non-static methods.
+ *
+ * To register it in the configuration file use the `phpstan.dynamicMethodThrowTypeExtension` service tag:
+ *
+ * ```
+ * services:
+ * 	-
+ *		class: App\PHPStan\MyExtension
+ *		tags:
+ *			- phpstan.dynamicMethodThrowTypeExtension
+ * ```
+ *
+ * Learn more: https://phpstan.org/developing-extensions/dynamic-throw-type-extensions
+ *
+ * @api
+ */
 interface DynamicMethodThrowTypeExtension
 {
 

diff --git a/src/Type/DynamicStaticMethodReturnTypeExtension.php b/src/Type/DynamicStaticMethodReturnTypeExtension.php
@@ -6,7 +6,23 @@
 use PHPStan\Analyser\Scope;
 use PHPStan\Reflection\MethodReflection;
 
-/** @api */
+/**
+ * This is the interface dynamic return type extensions implement for static methods.
+ *
+ * To register it in the configuration file use the `phpstan.broker.dynamicStaticMethodReturnTypeExtension` service tag:
+ *
+ * ```
+ * services:
+ * 	-
+ *		class: App\PHPStan\MyExtension
+ *		tags:
+ *			- phpstan.broker.dynamicStaticMethodReturnTypeExtension
+ * ```
+ *
+ * Learn more: https://phpstan.org/developing-extensions/dynamic-return-type-extensions
+ *
+ * @api
+ */
 interface DynamicStaticMethodReturnTypeExtension
 {
 

diff --git a/src/Type/DynamicStaticMethodThrowTypeExtension.php b/src/Type/DynamicStaticMethodThrowTypeExtension.php
@@ -6,7 +6,23 @@
 use PHPStan\Analyser\Scope;
 use PHPStan\Reflection\MethodReflection;
 
-/** @api */
+/**
+ * This is the interface dynamic throw type extensions implement for static methods.
+ *
+ * To register it in the configuration file use the `phpstan.dynamicStaticMethodThrowTypeExtension` service tag:
+ *
+ * ```
+ * services:
+ * 	-
+ *		class: App\PHPStan\MyExtension
+ *		tags:
+ *			- phpstan.dynamicStaticMethodThrowTypeExtension
+ * ```
+ *
+ * Learn more: https://phpstan.org/developing-extensions/dynamic-throw-type-extensions
+ *
+ * @api
+ */
 interface DynamicStaticMethodThrowTypeExtension
 {
 

diff --git a/src/Type/FunctionTypeSpecifyingExtension.php b/src/Type/FunctionTypeSpecifyingExtension.php
@@ -8,7 +8,23 @@
 use PHPStan\Analyser\TypeSpecifierContext;
 use PHPStan\Reflection\FunctionReflection;
 
-/** @api */
+/**
+ * This is the interface type-specifying extensions implement for functions.
+ *
+ * To register it in the configuration file use the `phpstan.typeSpecifier.functionTypeSpecifyingExtension` service tag:
+ *
+ * ```
+ * services:
+ * 	-
+ *		class: App\PHPStan\MyExtension
+ *		tags:
+ *			- phpstan.typeSpecifier.functionTypeSpecifyingExtension
+ * ```
+ *
+ * Learn more: https://phpstan.org/developing-extensions/type-specifying-extensions
+ *
+ * @api
+ */
 interface FunctionTypeSpecifyingExtension
 {