From 5f6fe47144a13a97e05576584b0e28d4cca5ac20 Mon Sep 17 00:00:00 2001
From: Garvin Hicking <blog@garv.in>
Date: Wed, 9 Apr 2025 17:36:16 +0200
Subject: [PATCH] [TASK] Add SchemaGenerator evaluation for "@see"

The phpDoc annotation "@see" contains valuable information
for the XSD schema generation for future reading.

Even though some IDEs like PHPStorm will not expose these links
as being clickable, they can be copied+pasted from a tooltip
in the IDE, and opened in the browser (instead of needing to
find and open a PHP classfile to get to that link).

Some IDEs (eclipse?) seem to be able to parse a HTML subset
for annotations, so maybe this will find future adoption
(or markdown rendering might get available). Since also
neither ReST nor Markdown is parsed in the XSD element
`xsd:documentation` by PHPStorm either.... plaintext it is!
---
 src/Schema/SchemaGenerator.php            |  6 +++
 tests/Unit/Schema/SchemaGeneratorTest.php | 55 +++++++++++++++++++++++
 2 files changed, 61 insertions(+)

diff --git a/src/Schema/SchemaGenerator.php b/src/Schema/SchemaGenerator.php
index 8a3283aea..f8acaa147 100644
--- a/src/Schema/SchemaGenerator.php
+++ b/src/Schema/SchemaGenerator.php
@@ -30,6 +30,12 @@ public function generate(string $xmlNamespace, array $viewHelpers): \SimpleXMLEl
             if (isset($metadata->docTags['@deprecated'])) {
                 $documentation .= "\n@deprecated " . $metadata->docTags['@deprecated'];
             }
+            // Add links from "@see" annotations. No HTML formatting means
+            // non-clickable links, but copy+paste from a URL is then possible
+            // for further reading
+            if (isset($metadata->docTags['@see'])) {
+                $documentation .= "\n@see " . $metadata->docTags['@see'];
+            }
             $documentation = trim($documentation);
 
             // Add documentation to xml
diff --git a/tests/Unit/Schema/SchemaGeneratorTest.php b/tests/Unit/Schema/SchemaGeneratorTest.php
index 65a1649e4..8783d5ce2 100644
--- a/tests/Unit/Schema/SchemaGeneratorTest.php
+++ b/tests/Unit/Schema/SchemaGeneratorTest.php
@@ -101,6 +101,61 @@ public static function generateSchemaDataProvider(): iterable
                 '</xsd:element>' .
                 '</xsd:schema>' . "\n",
             ],
+            'deprecatedViewHelperWithFurtherReading' => [
+                'http://typo3.org/ns/Vendor/Package/ViewHelpers',
+                [
+                    new ViewHelperMetadata(
+                        'Vendor\\Package\\ViewHelpers\\MyViewHelper',
+                        'Vendor\\Package',
+                        'MyViewHelper',
+                        'myViewHelper',
+                        '',
+                        'http://typo3.org/ns/Vendor/Package/ViewHelpers',
+                        [
+                            '@deprecated' => 'since 1.2.3, will be removed in 2.0.0',
+                            '@see' => 'https://docs.typo3.org/somelink',
+                        ],
+                        [],
+                        false,
+                    ),
+                ],
+                '<?xml version="1.0" encoding="UTF-8"?>' . "\n" .
+                '<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://typo3.org/ns/Vendor/Package/ViewHelpers">' .
+                '<xsd:element name="myViewHelper">' .
+                '<xsd:annotation><xsd:documentation><![CDATA[@deprecated since 1.2.3, will be removed in 2.0.0' . "\n" . '@see https://docs.typo3.org/somelink]]></xsd:documentation></xsd:annotation>' .
+                '<xsd:complexType mixed="true">' .
+                '<xsd:sequence><xsd:any minOccurs="0"/></xsd:sequence>' .
+                '</xsd:complexType>' .
+                '</xsd:element>' .
+                '</xsd:schema>' . "\n",
+            ],
+            'viewHelperWithFurtherReading' => [
+                'http://typo3.org/ns/Vendor/Package/ViewHelpers',
+                [
+                    new ViewHelperMetadata(
+                        'Vendor\\Package\\ViewHelpers\\MyViewHelper',
+                        'Vendor\\Package',
+                        'MyViewHelper',
+                        'myViewHelper',
+                        '',
+                        'http://typo3.org/ns/Vendor/Package/ViewHelpers',
+                        [
+                            '@see' => 'https://docs.typo3.org/somelink',
+                        ],
+                        [],
+                        false,
+                    ),
+                ],
+                '<?xml version="1.0" encoding="UTF-8"?>' . "\n" .
+                '<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://typo3.org/ns/Vendor/Package/ViewHelpers">' .
+                '<xsd:element name="myViewHelper">' .
+                '<xsd:annotation><xsd:documentation><![CDATA[@see https://docs.typo3.org/somelink]]></xsd:documentation></xsd:annotation>' .
+                '<xsd:complexType mixed="true">' .
+                '<xsd:sequence><xsd:any minOccurs="0"/></xsd:sequence>' .
+                '</xsd:complexType>' .
+                '</xsd:element>' .
+                '</xsd:schema>' . "\n",
+            ],
             'argumentTypes' => [
                 'http://typo3.org/ns/Vendor/Package/ViewHelpers',
                 [