From b76ede409c0628a8c43fad9ae9523918127eb50b Mon Sep 17 00:00:00 2001 From: DerManoMann Date: Wed, 8 Jul 2026 13:54:40 +1200 Subject: [PATCH] Add CS `phpdoc_line_span` rule for class/method docblocks Enforces multi-line docblocks on class/interface/trait/enum and method declarations while preserving existing style for properties and constants. Co-Authored-By: Claude Opus 4.6 --- .php-cs-fixer.dist.php | 1 + docs/snippets/guide/cookbook/enums_an.php | 8 ++++++-- src/Generator.php | 4 +++- src/Type/LegacyTypeResolver.php | 4 +++- src/Type/TypeInfoTypeResolver.php | 4 +++- tests/Fixtures/Scratch/ComplexCustomAttributes.php | 12 +++++++++--- tests/Fixtures/Scratch/CustomAttributes.php | 8 ++++++-- 7 files changed, 31 insertions(+), 10 deletions(-) diff --git a/.php-cs-fixer.dist.php b/.php-cs-fixer.dist.php index 25fe8fdb0..c3717065c 100644 --- a/.php-cs-fixer.dist.php +++ b/.php-cs-fixer.dist.php @@ -98,6 +98,7 @@ 'phpdoc_no_alias_tag' => true, 'phpdoc_param_order' => true, 'multiline_comment_opening_closing' => true, + 'phpdoc_line_span' => ['class' => 'multi', 'method' => 'multi', 'property' => null, 'const' => null, 'case' => null, 'function' => null], 'php_unit_attributes' => true, ]) diff --git a/docs/snippets/guide/cookbook/enums_an.php b/docs/snippets/guide/cookbook/enums_an.php index dd919355a..1cd1a3d04 100644 --- a/docs/snippets/guide/cookbook/enums_an.php +++ b/docs/snippets/guide/cookbook/enums_an.php @@ -4,7 +4,9 @@ use OpenApi\Annotations as OA; -/** @OA\Schema() */ +/** + * @OA\Schema() + */ enum State { case OPEN; @@ -12,7 +14,9 @@ enum State case DECLINED; } -/** @OA\Schema */ +/** + * @OA\Schema + */ class PullRequest { /** @OA\Property */ diff --git a/src/Generator.php b/src/Generator.php index e8543f322..6f79d1ca4 100644 --- a/src/Generator.php +++ b/src/Generator.php @@ -73,7 +73,9 @@ public function __construct(?LoggerInterface $logger = null) $this->setNamespaces(self::DEFAULT_NAMESPACES); } - /** @deprecated Use {@see Undefined::isDefault()} instead. */ + /** + * @deprecated use {@see Undefined::isDefault()} instead + */ public static function isDefault(...$value): bool { return Undefined::isDefault(...$value); diff --git a/src/Type/LegacyTypeResolver.php b/src/Type/LegacyTypeResolver.php index 33340f77f..85e64966a 100644 --- a/src/Type/LegacyTypeResolver.php +++ b/src/Type/LegacyTypeResolver.php @@ -17,7 +17,9 @@ */ class LegacyTypeResolver extends AbstractTypeResolver { - /** @inheritdoc */ + /** + * @inheritdoc + */ protected function doAugment(Analysis $analysis, OA\Schema $schema, \Reflector $reflector, string $sourceClass = OA\Schema::class): void { $docblockDetails = $this->getDocblockTypeDetails($reflector, $schema->_context); diff --git a/src/Type/TypeInfoTypeResolver.php b/src/Type/TypeInfoTypeResolver.php index 0802908d6..7220fb890 100644 --- a/src/Type/TypeInfoTypeResolver.php +++ b/src/Type/TypeInfoTypeResolver.php @@ -37,7 +37,9 @@ class TypeInfoTypeResolver extends AbstractTypeResolver { - /** @inheritdoc */ + /** + * @inheritdoc + */ protected function doAugment(Analysis $analysis, OA\Schema $schema, \Reflector $reflector, string $sourceClass = OA\Schema::class): void { $docblockType = $this->getDocblockType($reflector); diff --git a/tests/Fixtures/Scratch/ComplexCustomAttributes.php b/tests/Fixtures/Scratch/ComplexCustomAttributes.php index cf1794487..ea30a3e98 100644 --- a/tests/Fixtures/Scratch/ComplexCustomAttributes.php +++ b/tests/Fixtures/Scratch/ComplexCustomAttributes.php @@ -66,7 +66,9 @@ public function __construct( )] class Collection extends OAT\Property { - /** @param class-string $of */ + /** + * @param class-string $of + */ public function __construct( string $of, ?string $description = null @@ -90,7 +92,9 @@ public function __construct( )] class Item extends OAT\Property { - /** @param class-string $of */ + /** + * @param class-string $of + */ public function __construct( string $of, ?string $description = null @@ -128,7 +132,9 @@ public function __construct( #[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)] class Successful extends OAT\Response { - /** @param ?class-string $of */ + /** + * @param ?class-string $of + */ public function __construct( ?string $of = null, ) { diff --git a/tests/Fixtures/Scratch/CustomAttributes.php b/tests/Fixtures/Scratch/CustomAttributes.php index 8409fa6be..04b91bce5 100644 --- a/tests/Fixtures/Scratch/CustomAttributes.php +++ b/tests/Fixtures/Scratch/CustomAttributes.php @@ -28,7 +28,9 @@ class CustomProperty extends OAT\Property #[\Attribute(\Attribute::TARGET_METHOD | \Attribute::TARGET_PROPERTY | \Attribute::TARGET_PARAMETER | \Attribute::TARGET_CLASS_CONSTANT | \Attribute::IS_REPEATABLE)] class CustomItem extends OAT\Property { - /** @param class-string $of */ + /** + * @param class-string $of + */ public function __construct( string $of, ?string $description = null @@ -44,7 +46,9 @@ public function __construct( #[\Attribute(\Attribute::TARGET_METHOD | \Attribute::TARGET_PROPERTY | \Attribute::TARGET_PARAMETER | \Attribute::TARGET_CLASS_CONSTANT | \Attribute::IS_REPEATABLE)] class CustomList extends OAT\Property { - /** @param class-string $of */ + /** + * @param class-string $of + */ public function __construct(string $of, ?string $description = null) { parent::__construct(