[PhpUnitBridge] Deprecate the expectedDeprecation annotation

Author: javiereguiluz

components/phpunit_bridge.rst

@@ -335,23 +335,41 @@ Write Assertions about Deprecations
 
 When adding deprecations to your code, you might like writing tests that verify
 that they are triggered as required. To do so, the bridge provides the
-``@expectedDeprecation`` annotation that you can use on your test methods.
+``expectDeprecation()`` method that you can use on your test methods.
 It requires you to pass the expected message, given in the same format as for
 the `PHPUnit's assertStringMatchesFormat()`_ method. If you expect more than one
-deprecation message for a given test method, you can use the annotation several
+deprecation message for a given test method, you can use the method several
 times (order matters)::
 
-    /**
-     * @group legacy
-     * @expectedDeprecation This "%s" method is deprecated.
-     * @expectedDeprecation The second argument of the "%s" method is deprecated.
-     */
-    public function testDeprecatedCode()
+    use PHPUnit\Framework\TestCase;
+    use Symfony\Bridge\PhpUnit\ExpectDeprecationTrait;
+
+    class MyTest extends TestCase
     {
-        @trigger_error('This "Foo" method is deprecated.', E_USER_DEPRECATED);
-        @trigger_error('The second argument of the "Bar" method is deprecated.', E_USER_DEPRECATED);
+        use ExpectDeprecationTrait;
+
+        /**
+         * @group legacy
+         */
+        public function testDeprecatedCode()
+        {
+            // test some code that triggers the following deprecation:
+            // @trigger_error('This "Foo" method is deprecated.', E_USER_DEPRECATED);
+            $this->expectDeprecation('This "%s" method is deprecated');
+
+            // ...
+
+            // test some code that triggers the following deprecation:
+            // @trigger_error('The second argument of the "Bar" method is deprecated.', E_USER_DEPRECATED);
+            $this->expectDeprecation('The second argument of the "%s" method is deprecated.');
+        }
     }
 
+.. deprecated:: 5.1
+
+    Symfony versions previous to 5.1 also included a ``@expectedDeprecation``
+    annotation to test deprecations, but it was deprecated in favor of the method.
+
 Display the Full Stack Trace
 ----------------------------