More rich PHPDocs for extension interfaces

Author: ondrejmirtes

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

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
 {
 

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
 {
 

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
 {
 

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
 {
 

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
 {
 

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
 {
 

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
 {
 

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
 {
 

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
 {