[TASK] Add SchemaGenerator evaluation for "@see" (#1047)

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!

Author: garvinhicking

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

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',
                 [