feat(metadata): document BackwardCompatibleFilterDescriptionTrait as public API (#8326)

Author: soyuka

src/Metadata/BackwardCompatibleFilterDescriptionTrait.php

@@ -14,9 +14,13 @@
 namespace ApiPlatform\Metadata;
 
 /**
- * @author Vincent Amstoutz <vincent.amstoutz.dev@gmail.com>
+ * Lets a filter satisfy the legacy FilterInterface::getDescription() requirement without implementing it by hand.
+ *
+ * Use this trait in a filter that does not need to describe itself through the deprecated getDescription() mechanism:
+ * it returns an empty array, which is the expected value now that filters are described through QueryParameter metadata.
+ * The trait will be removed in 6.0 together with FilterInterface::getDescription().
  *
- * @internal
+ * @author Vincent Amstoutz <vincent.amstoutz.dev@gmail.com>
  */
 trait BackwardCompatibleFilterDescriptionTrait
 {

src/Metadata/Tests/BackwardCompatibleFilterDescriptionTraitTest.php

@@ -0,0 +1,29 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <dunglas@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace ApiPlatform\Metadata\Tests;
+
+use ApiPlatform\Metadata\BackwardCompatibleFilterDescriptionTrait;
+use PHPUnit\Framework\TestCase;
+
+final class BackwardCompatibleFilterDescriptionTraitTest extends TestCase
+{
+    public function testGetDescriptionReturnsEmptyArray(): void
+    {
+        $filter = new class {
+            use BackwardCompatibleFilterDescriptionTrait;
+        };
+
+        $this->assertSame([], $filter->getDescription('Foo'));
+    }
+}