support description as well

Author: Daniel Kurowski

src/Capabilities/Deprecated.php

@@ -14,7 +14,8 @@ final class Deprecated implements Capability
 	 * @param class-string $replacement
 	 */
 	public function __construct(
-		private string $replacement,
+		private ?string $description = null,
+		private ?string $replacement = null,
 	) {}
 
 
@@ -24,10 +25,17 @@ public function applyTo(
 		?ClassInNamespace $current,
 	): void
 	{
-		$draft->getClassType()->addComment(sprintf(
-			"@deprecated use {@see %s} instead",
-			$this->replacement,
-		));
+		$annotation = '@deprecated';
+		if ($this->description !== null) {
+			$annotation .= ' ' . $this->description;
+		}
+
+		if ($this->replacement !== null) {
+			$annotation .= $this->description !== null ? ', ' : ' ';
+			$annotation .= sprintf('use {@see %s} instead', $this->replacement);
+		}
+
+		$draft->getClassType()->addComment($annotation);
 	}
 
 }

src/Capabilities/functions.php

@@ -11,8 +11,11 @@ function constructorWithPromotedProperties(): ConstructorWithPromotedProperties
 /**
  * @param class-string $replacement
  */
-function deprecated(string $replacement): Deprecated {
-	return new Deprecated($replacement);
+function deprecated(
+	?string $description = null,
+	?string $replacement = null,
+): Deprecated {
+	return new Deprecated($description, $replacement);
 }
 
 function getters(): Getters {

tests/Capabilities/Deprecated/DeprecatedTest.expected.onlyAnnotation.phps

@@ -0,0 +1,14 @@
+<?php
+
+/**
+ * Do not edit. This is generated file. Modify definition file instead.
+ */
+
+declare(strict_types=1);
+
+/**
+ * @deprecated
+ */
+final class ClassName
+{
+}

tests/Capabilities/Deprecated/DeprecatedTest.expected.withAll.phps

@@ -0,0 +1,14 @@
+<?php
+
+/**
+ * Do not edit. This is generated file. Modify definition file instead.
+ */
+
+declare(strict_types=1);
+
+/**
+ * @deprecated will be removed in v4.0.0, use {@see Grifart\ClassScaffolder\Test\Capabilities\Deprecated\Replacement} instead
+ */
+final class ClassName
+{
+}

tests/Capabilities/Deprecated/DeprecatedTest.expected.withDescription.phps

@@ -0,0 +1,14 @@
+<?php
+
+/**
+ * Do not edit. This is generated file. Modify definition file instead.
+ */
+
+declare(strict_types=1);
+
+/**
+ * @deprecated will be removed in v4.0.0
+ */
+final class ClassName
+{
+}

tests/Capabilities/Deprecated/DeprecatedTest.expected.phps renamed to tests/Capabilities/Deprecated/DeprecatedTest.expected.withReplacement.phps

@@ -6,10 +6,6 @@
 
 declare(strict_types=1);
 
-namespace RootNamespace\SubNamespace;
-
-use Iterator;
-
 /**
  * @deprecated use {@see Grifart\ClassScaffolder\Test\Capabilities\Deprecated\Replacement} instead
  */

tests/Capabilities/Deprecated/DeprecatedTest.phpt

@@ -2,19 +2,67 @@
 
 namespace Grifart\ClassScaffolder\Test\Capabilities\Deprecated;
 
-use Grifart\ClassScaffolder\Test\Capabilities\CapabilityTestCase;
+use Grifart\ClassScaffolder\ClassGenerator;
+use Grifart\ClassScaffolder\Definition\ClassDefinition;
+use Tester\Assert;
+use Tester\TestCase;
 use function Grifart\ClassScaffolder\Capabilities\deprecated;
+use function Grifart\ClassScaffolder\Definition\definitionOf;
 
 
 require __DIR__ . '/../../bootstrap.php';
 
-final class DeprecatedTest extends CapabilityTestCase
+final class DeprecatedTest extends TestCase
 {
-	protected function getCapabilities(): array
+	private function doAssert(
+		ClassDefinition $definition,
+		string $expectedFilePath,
+	): void
 	{
-		return [
-			deprecated(Replacement::class),
-		];
+		$generator = new ClassGenerator();
+		$phpFile = $generator->generateClass($definition);
+		$code = (string) $phpFile;
+
+		Assert::matchFile($expectedFilePath, $code);
+	}
+
+	public function testWithoutParams(): void
+	{
+		$this->doAssert(
+			definition: definitionOf('ClassName')
+				->with(deprecated()),
+			expectedFilePath: __DIR__ . '/DeprecatedTest.expected.onlyAnnotation.phps',
+		);
+	}
+
+	public function testWithDescription(): void
+	{
+		$this->doAssert(
+			definition: definitionOf('ClassName')
+				->with(deprecated(description: 'will be removed in v4.0.0')),
+			expectedFilePath: __DIR__ . '/DeprecatedTest.expected.withDescription.phps',
+		);
+	}
+
+	public function testWithReplacement(): void
+	{
+		$this->doAssert(
+			definition: definitionOf('ClassName')
+				->with(deprecated(replacement: Replacement::class)),
+			expectedFilePath: __DIR__ . '/DeprecatedTest.expected.withReplacement.phps',
+		);
+	}
+
+	public function testWithAll(): void
+	{
+		$this->doAssert(
+			definition: definitionOf('ClassName')
+				->with(deprecated(
+					description: 'will be removed in v4.0.0',
+					replacement: Replacement::class,
+				)),
+			expectedFilePath: __DIR__ . '/DeprecatedTest.expected.withAll.phps',
+		);
 	}
 }