Add Deprecated attribute

Author: carlos-granados

Diff for: README.md

@@ -94,6 +94,7 @@ These are the available attributes and their corresponding PHPDoc annotations:
 
 | Attribute                                             | PHPDoc Annotations        |
 |-------------------------------------------------------|---------------------------|
+| [Deprecated](doc/Deprecated.md)                       | `@deprecated`             |
 | [IsReadOnly](doc/IsReadOnly.md)                       | `@readonly`               |
 | [Method](doc/Method.md)                               | `@method`                 |
 | [Param](doc/Param.md)                                 | `@param`                  |

Diff for: doc/Deprecated.md

@@ -0,0 +1,24 @@
+# `Deprecated` Attribute
+
+This attribute is the equivalent of the `@deprecated` annotation for classes, traits, interfaces, class properties, class methods, class constants and functions.
+
+## Arguments
+
+The attribute accepts no arguments.
+
+## Example usage
+
+```php
+<?php
+
+use PhpStaticAnalysis\Attributes\Deprecated;
+
+#[Deprecated] // Use NotDeprecatedClass instead
+class DeprecatedExample
+{
+    #[Deprecated]
+    public function getName(): string;
+    
+    ...
+}
+```

Diff for: src/Deprecated.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpStaticAnalysis\Attributes;
+
+use Attribute;
+
+#[Attribute(
+    Attribute::TARGET_CLASS |
+    Attribute::TARGET_METHOD |
+    Attribute::TARGET_FUNCTION |
+    Attribute::TARGET_PROPERTY |
+    Attribute::TARGET_CLASS_CONSTANT
+)]
+final class Deprecated
+{
+    public function __construct()
+    {
+    }
+}

Diff for: tests/DeprecatedTest.php

@@ -0,0 +1,109 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpStaticAnalysis\Attributes\Deprecated;
+use PHPUnit\Framework\TestCase;
+
+#[Deprecated]
+class DeprecatedTest extends TestCase
+{
+    #[Deprecated]
+    public string $property;
+
+    public function testDeprecatedProperty(): void
+    {
+        $reflection = new ReflectionProperty($this, 'property');
+        $this->assertTrue(self::getDeprecatedFromReflection($reflection));
+    }
+
+    public function testClassDeprecated(): void
+    {
+        $reflection = new ReflectionClass($this);
+        $this->assertTrue(self::getDeprecatedFromReflection($reflection));
+    }
+
+    public function testTraitDeprecated(): void
+    {
+        $reflection = new ReflectionClass(DeprecatedTestTrait::class);
+        $this->assertTrue(self::getDeprecatedFromReflection($reflection));
+    }
+
+    public function testInterfaceDeprecated(): void
+    {
+        $reflection = new ReflectionClass(DeprecatedTestInterface::class);
+        $this->assertTrue(self::getDeprecatedFromReflection($reflection));
+    }
+
+    public function testMethodDeprecated(): void
+    {
+        $this->assertTrue($this->methodDeprecated());
+    }
+
+    public function testInvalidTypeMethodDeprecated(): void
+    {
+        $errorThrown = false;
+        try {
+            $this->invalidTypeMethodDeprecated();
+        } catch (Error $e) {
+            $errorThrown = true;
+        }
+        $this->assertTrue($errorThrown);
+    }
+
+    public function testFunctionDeprecated(): void
+    {
+        $this->assertTrue(functionDeprecated());
+    }
+
+    #[Deprecated]
+    private function methodDeprecated(): bool
+    {
+        return $this->getDeprecated(__FUNCTION__);
+    }
+
+    #[Deprecated]
+    #[Deprecated]
+    private function invalidTypeMethodDeprecated(): bool
+    {
+        return $this->getDeprecated(__FUNCTION__);
+    }
+
+    private function getDeprecated(string $methodName): bool
+    {
+        $reflection = new ReflectionMethod($this, $methodName);
+        return self::getDeprecatedFromReflection($reflection);
+    }
+
+    public static function getDeprecatedFromReflection(
+        ReflectionMethod | ReflectionFunction | ReflectionClass | ReflectionProperty $reflection
+    ): bool {
+        $attributes = $reflection->getAttributes();
+        $deprecated = false;
+        foreach ($attributes as $attribute) {
+            if ($attribute->getName() === Deprecated::class) {
+                $attribute->newInstance();
+                $deprecated = true;
+            }
+        }
+
+        return $deprecated;
+    }
+}
+
+#[Deprecated]
+trait DeprecatedTestTrait
+{
+}
+
+#[Deprecated]
+interface DeprecatedTestInterface
+{
+}
+
+#[Deprecated]
+function functionDeprecated(): bool
+{
+    $reflection = new ReflectionFunction(__FUNCTION__);
+    return DeprecatedTest::getDeprecatedFromReflection($reflection);
+}

Diff for: tests/IsReadOnlyTest.php

@@ -27,12 +27,12 @@ public function __construct()
 
     public function testReadOnlyProperty(): void
     {
-        $this->assertEquals(true, $this->readOnlyProperty());
+        $this->assertTrue($this->readOnlyProperty());
     }
 
     public function testReadOnlyPropertyWithValue(): void
     {
-        $this->assertEquals(true, $this->readOnlyPropertyWithValue());
+        $this->assertTrue($this->readOnlyPropertyWithValue());
     }
 
     public function testMultipleReadOnly(): void