* Update documentation for TestListener deprecation

* Document that the Hook interfaces will be removed in PHPUnit 10

Author: sebastianbergmann

src/Framework/TestListener.php

@@ -12,73 +12,32 @@
 use Throwable;
 
 /**
- * @deprecated Use the `TestHook` interfaces instead
+ * This interface, as well as the associated mechanism for extending PHPUnit,
+ * will be removed in PHPUnit 10. There is no alternative available in this
+ * version of PHPUnit.
+ *
+ * @deprecated
+ * @see https://github.com/sebastianbergmann/phpunit/issues/4676
  */
 interface TestListener
 {
-    /**
-     * An error occurred.
-     *
-     * @deprecated Use `AfterTestErrorHook::executeAfterTestError` instead
-     */
     public function addError(Test $test, Throwable $t, float $time): void;
 
-    /**
-     * A warning occurred.
-     *
-     * @deprecated Use `AfterTestWarningHook::executeAfterTestWarning` instead
-     */
     public function addWarning(Test $test, Warning $e, float $time): void;
 
-    /**
-     * A failure occurred.
-     *
-     * @deprecated Use `AfterTestFailureHook::executeAfterTestFailure` instead
-     */
     public function addFailure(Test $test, AssertionFailedError $e, float $time): void;
 
-    /**
-     * Incomplete test.
-     *
-     * @deprecated Use `AfterIncompleteTestHook::executeAfterIncompleteTest` instead
-     */
     public function addIncompleteTest(Test $test, Throwable $t, float $time): void;
 
-    /**
-     * Risky test.
-     *
-     * @deprecated Use `AfterRiskyTestHook::executeAfterRiskyTest` instead
-     */
     public function addRiskyTest(Test $test, Throwable $t, float $time): void;
 
-    /**
-     * Skipped test.
-     *
-     * @deprecated Use `AfterSkippedTestHook::executeAfterSkippedTest` instead
-     */
     public function addSkippedTest(Test $test, Throwable $t, float $time): void;
 
-    /**
-     * A test suite started.
-     */
     public function startTestSuite(TestSuite $suite): void;
 
-    /**
-     * A test suite ended.
-     */
     public function endTestSuite(TestSuite $suite): void;
 
-    /**
-     * A test started.
-     *
-     * @deprecated Use `BeforeTestHook::executeBeforeTest` instead
-     */
     public function startTest(Test $test): void;
 
-    /**
-     * A test ended.
-     *
-     * @deprecated Use `AfterTestHook::executeAfterTest` instead
-     */
     public function endTest(Test $test, float $time): void;
 }

src/Runner/Hook/AfterIncompleteTestHook.php

@@ -9,6 +9,13 @@
  */
 namespace PHPUnit\Runner;
 
+/**
+ * This interface, as well as the associated mechanism for extending PHPUnit,
+ * will be removed in PHPUnit 10. There is no alternative available in this
+ * version of PHPUnit.
+ *
+ * @see https://github.com/sebastianbergmann/phpunit/issues/4676
+ */
 interface AfterIncompleteTestHook extends TestHook
 {
     public function executeAfterIncompleteTest(string $test, string $message, float $time): void;

src/Runner/Hook/AfterLastTestHook.php

@@ -9,6 +9,13 @@
  */
 namespace PHPUnit\Runner;
 
+/**
+ * This interface, as well as the associated mechanism for extending PHPUnit,
+ * will be removed in PHPUnit 10. There is no alternative available in this
+ * version of PHPUnit.
+ *
+ * @see https://github.com/sebastianbergmann/phpunit/issues/4676
+ */
 interface AfterLastTestHook extends Hook
 {
     public function executeAfterLastTest(): void;

src/Runner/Hook/AfterRiskyTestHook.php

@@ -9,6 +9,13 @@
  */
 namespace PHPUnit\Runner;
 
+/**
+ * This interface, as well as the associated mechanism for extending PHPUnit,
+ * will be removed in PHPUnit 10. There is no alternative available in this
+ * version of PHPUnit.
+ *
+ * @see https://github.com/sebastianbergmann/phpunit/issues/4676
+ */
 interface AfterRiskyTestHook extends TestHook
 {
     public function executeAfterRiskyTest(string $test, string $message, float $time): void;

src/Runner/Hook/AfterSkippedTestHook.php

@@ -9,6 +9,13 @@
  */
 namespace PHPUnit\Runner;
 
+/**
+ * This interface, as well as the associated mechanism for extending PHPUnit,
+ * will be removed in PHPUnit 10. There is no alternative available in this
+ * version of PHPUnit.
+ *
+ * @see https://github.com/sebastianbergmann/phpunit/issues/4676
+ */
 interface AfterSkippedTestHook extends TestHook
 {
     public function executeAfterSkippedTest(string $test, string $message, float $time): void;

src/Runner/Hook/AfterSuccessfulTestHook.php

@@ -9,6 +9,13 @@
  */
 namespace PHPUnit\Runner;
 
+/**
+ * This interface, as well as the associated mechanism for extending PHPUnit,
+ * will be removed in PHPUnit 10. There is no alternative available in this
+ * version of PHPUnit.
+ *
+ * @see https://github.com/sebastianbergmann/phpunit/issues/4676
+ */
 interface AfterSuccessfulTestHook extends TestHook
 {
     public function executeAfterSuccessfulTest(string $test, float $time): void;

src/Runner/Hook/AfterTestErrorHook.php

@@ -9,6 +9,13 @@
  */
 namespace PHPUnit\Runner;
 
+/**
+ * This interface, as well as the associated mechanism for extending PHPUnit,
+ * will be removed in PHPUnit 10. There is no alternative available in this
+ * version of PHPUnit.
+ *
+ * @see https://github.com/sebastianbergmann/phpunit/issues/4676
+ */
 interface AfterTestErrorHook extends TestHook
 {
     public function executeAfterTestError(string $test, string $message, float $time): void;

src/Runner/Hook/AfterTestFailureHook.php

@@ -9,6 +9,13 @@
  */
 namespace PHPUnit\Runner;
 
+/**
+ * This interface, as well as the associated mechanism for extending PHPUnit,
+ * will be removed in PHPUnit 10. There is no alternative available in this
+ * version of PHPUnit.
+ *
+ * @see https://github.com/sebastianbergmann/phpunit/issues/4676
+ */
 interface AfterTestFailureHook extends TestHook
 {
     public function executeAfterTestFailure(string $test, string $message, float $time): void;

src/Runner/Hook/AfterTestHook.php

@@ -9,6 +9,13 @@
  */
 namespace PHPUnit\Runner;
 
+/**
+ * This interface, as well as the associated mechanism for extending PHPUnit,
+ * will be removed in PHPUnit 10. There is no alternative available in this
+ * version of PHPUnit.
+ *
+ * @see https://github.com/sebastianbergmann/phpunit/issues/4676
+ */
 interface AfterTestHook extends TestHook
 {
     /**

src/Runner/Hook/AfterTestWarningHook.php

@@ -9,6 +9,13 @@
  */
 namespace PHPUnit\Runner;
 
+/**
+ * This interface, as well as the associated mechanism for extending PHPUnit,
+ * will be removed in PHPUnit 10. There is no alternative available in this
+ * version of PHPUnit.
+ *
+ * @see https://github.com/sebastianbergmann/phpunit/issues/4676
+ */
 interface AfterTestWarningHook extends TestHook
 {
     public function executeAfterTestWarning(string $test, string $message, float $time): void;

src/Runner/Hook/BeforeFirstTestHook.php

@@ -9,6 +9,13 @@
  */
 namespace PHPUnit\Runner;
 
+/**
+ * This interface, as well as the associated mechanism for extending PHPUnit,
+ * will be removed in PHPUnit 10. There is no alternative available in this
+ * version of PHPUnit.
+ *
+ * @see https://github.com/sebastianbergmann/phpunit/issues/4676
+ */
 interface BeforeFirstTestHook extends Hook
 {
     public function executeBeforeFirstTest(): void;

src/Runner/Hook/BeforeTestHook.php

@@ -9,6 +9,13 @@
  */
 namespace PHPUnit\Runner;
 
+/**
+ * This interface, as well as the associated mechanism for extending PHPUnit,
+ * will be removed in PHPUnit 10. There is no alternative available in this
+ * version of PHPUnit.
+ *
+ * @see https://github.com/sebastianbergmann/phpunit/issues/4676
+ */
 interface BeforeTestHook extends TestHook
 {
     public function executeBeforeTest(string $test): void;

src/Runner/Hook/Hook.php

@@ -9,6 +9,13 @@
  */
 namespace PHPUnit\Runner;
 
+/**
+ * This interface, as well as the associated mechanism for extending PHPUnit,
+ * will be removed in PHPUnit 10. There is no alternative available in this
+ * version of PHPUnit.
+ *
+ * @see https://github.com/sebastianbergmann/phpunit/issues/4676
+ */
 interface Hook
 {
 }

src/Runner/Hook/TestHook.php

@@ -9,6 +9,13 @@
  */
 namespace PHPUnit\Runner;
 
+/**
+ * This interface, as well as the associated mechanism for extending PHPUnit,
+ * will be removed in PHPUnit 10. There is no alternative available in this
+ * version of PHPUnit.
+ *
+ * @see https://github.com/sebastianbergmann/phpunit/issues/4676
+ */
 interface TestHook extends Hook
 {
 }