Improve phpdomain templates (#45)

* [BUGFIX] Remove duplicate colon after "Returns" * [TASK] Extract display of vendor from component name * [TASK] Use partial includes for method names and FQNs * [TASK] Use partial includes for method names and FQNs
TYPO3-Documentation · May 15, 2024 · 6a7f45d · 6a7f45d
1 parent 91219d4
commit 6a7f45d
Show file tree

Hide file tree

Showing 59 changed files with 426 additions and 153 deletions.
diff --git a/.github/workflows/main.yaml b/.github/workflows/main.yaml
@@ -56,5 +56,3 @@ jobs:
         run: "make code-style"
       - name: "Run static code analysis"
         run: "make phpstan"
-      - name: "Run rector"
-        run: "make rector-dry"
diff --git a/Makefile b/Makefile
@@ -34,4 +34,4 @@ test-unit: ## Runs unit tests with phpunit
 	vendor/bin/phpunit --testsuite=unit
 
 .PHONY: test
-test: test-integration test-unit ## Runs all test suites with phpunit
+test: fix-code-style phpstan test-integration test-unit ## Runs all test suites with phpunit
diff --git a/phpstan-baseline.neon b/phpstan-baseline.neon
@@ -2,7 +2,7 @@ parameters:
 	ignoreErrors:
 		-
 			message: "#^Function phpDocumentor\\\\Guides\\\\DependencyInjection\\\\template not found\\.$#"
-			count: 11
+			count: 9
 			path: src/DependencyInjection/GuidesPhpDomainExtension.php
 
 		-

diff --git a/resources/template/html/body/directive/php/component.html.twig b/resources/template/html/body/directive/php/component.html.twig
@@ -1,14 +1,26 @@
+{%- if node.name.namespaceNode %}{%- set fqn = '\\' ~ node.name.namespaceNode.name ~ '\\' ~ node.name.namespaceNode.name -%}{% endif -%}
 <dl class="php {{ node.type }}">
     <dt class="sig sig-object php"
         {%- if not node.noindex %} id="{{ node.id }}"{% endif -%}>
         {% for modifier in node.modifiers -%}
             {{- renderNode(modifier) }}{{ ' ' -}}
         {%- endfor -%}
         <em class="property"><span class="pre">{{ node.type }}</span> </em>
-        {{ renderNode(node.name) }} {%- if node.type == 'enum' and node.phpType -%}<span class="pre"> : {{ node.phpType }}</span> {% endif -%}
+        {% include "body/directive/php/partials/fullyQualifiedName.html.twig" with {'className': node.name, 'fqn': fqn} %}
+        {%- if node.type == 'enum' and node.phpType -%}<span class="pre"> : {{ node.phpType }}</span> {% endif -%}
         {% include "body/directive/php/partials/linkToSnippet.html.twig" %}
     </dt>
     <dd>
+        {% if node.name.namespaceNode %}
+            <dl class="field-list simple">
+                {% if node.name.namespaceNode %}
+                    <dt class="field-even">Fully qualified name</dt>
+                    <dd class="field-even">
+                        {% include "body/directive/php/partials/codeStyle.html.twig" with {'code': fqn} %}
+                    </dd>
+                {% endif -%}
+            </dl>
+        {% endif -%}
         {{ renderNode(node.value) }}
     </dd>
 </dl>
diff --git a/resources/template/html/body/directive/php/fullyQualifiedName.html.twig b/resources/template/html/body/directive/php/fullyQualifiedName.html.twig
diff --git a/resources/template/html/body/directive/php/method.html.twig b/resources/template/html/body/directive/php/method.html.twig
@@ -3,14 +3,14 @@
         {%- for modifier in node.modifiers -%}
             {{- renderNode(modifier) }}{{ ' ' -}}
         {%- endfor -%}
-        {{- renderNode(node.methodName) -}}
+        {% include "body/directive/php/partials/method/methodName.html.twig" with {'methodName': node.methodName} %}
         {% include "body/directive/php/partials/linkToSnippet.html.twig" %}
     </dt>
     <dd>
         {{ renderNode(node.value) }}
         {% if node.returnsDescription %}
             <dl class="field-list simple">
-                <dt class="field-even">Returns:</dt>
+                <dt class="field-even">Returns</dt>
                 <dd class="field-even">
                     {{ renderNode(node.returnsDescription) }}
                 </dd>

diff --git a/resources/template/html/body/directive/php/methodName.html.twig b/resources/template/html/body/directive/php/methodName.html.twig
diff --git a/resources/template/html/body/directive/php/partials/codeStyle.html.twig b/resources/template/html/body/directive/php/partials/codeStyle.html.twig
@@ -0,0 +1 @@
+<span class="pre">{{ code|raw }}</span>
diff --git a/resources/template/html/body/directive/php/partials/fullyQualifiedName.html.twig b/resources/template/html/body/directive/php/partials/fullyQualifiedName.html.twig
@@ -0,0 +1,6 @@
+<span class="sig-name descname">
+    <span class="pre fqn"
+        {%- if fqn %} data-fqn="{{ fqn }}" title="{{ fqn }}"{% endif %}>
+        {{- className.name -}}
+    </span>
+</span>
diff --git a/resources/template/html/body/directive/php/partials/method/methodName.html.twig b/resources/template/html/body/directive/php/partials/method/methodName.html.twig
@@ -0,0 +1,15 @@
+
+<span class="sig-name descname">
+    {%- for modifier in methodName.modifiers -%}
+        <span class="pre php-modifier">{{- renderNode(modifier) }}{{ ' ' -}}</span>
+    {%- endfor -%}
+    <span class="pre">{{ methodName.name }}</span></span>
+<span class="sig-paren">(</span>
+{% for param in methodName.params -%}
+    <em class="sig-param"><span class="pre">{{ param }}</span></em>
+    {%- if not loop.last %}, {% endif -%}
+{%- endfor %}
+<span class="sig-paren">)</span>
+{% if methodName.return %}
+<em class="sig-returns"><span class="pre">: {{ methodName.return }}</span></em>
+{% endif %}
diff --git a/src/DependencyInjection/GuidesPhpDomainExtension.php b/src/DependencyInjection/GuidesPhpDomainExtension.php
@@ -9,9 +9,7 @@
 use Symfony\Component\DependencyInjection\Extension\Extension;
 use Symfony\Component\DependencyInjection\Extension\PrependExtensionInterface;
 use Symfony\Component\DependencyInjection\Loader\PhpFileLoader;
-use T3Docs\GuidesPhpDomain\Nodes\FullyQualifiedNameNode;
 use T3Docs\GuidesPhpDomain\Nodes\MemberNameNode;
-use T3Docs\GuidesPhpDomain\Nodes\MethodNameNode;
 use T3Docs\GuidesPhpDomain\Nodes\PhpCaseNode;
 use T3Docs\GuidesPhpDomain\Nodes\PhpComponentNode;
 use T3Docs\GuidesPhpDomain\Nodes\PhpConstNode;
@@ -44,7 +42,6 @@ public function prepend(ContainerBuilder $container): void
             [
                 'base_template_paths' => [dirname(__DIR__, 2) . '/resources/template/html'],
                 'templates' => [
-                    template(FullyQualifiedNameNode::class, 'body/directive/php/fullyQualifiedName.html.twig'),
                     template(PhpCaseNode::class, 'body/directive/php/case.html.twig'),
                     template(PhpComponentNode::class, 'body/directive/php/component.html.twig'),
                     template(PhpConstNode::class, 'body/directive/php/const.html.twig'),
@@ -54,7 +51,6 @@ public function prepend(ContainerBuilder $container): void
                     template(PhpPropertyNode::class, 'body/directive/php/property.html.twig'),
                     template(PhpModifierNode::class, 'body/directive/php/modifier.html.twig'),
                     template(MemberNameNode::class, 'body/directive/php/memberName.html.twig'),
-                    template(MethodNameNode::class, 'body/directive/php/methodName.html.twig'),
                 ],
             ],
         );

diff --git a/tests/integration/class-abstract/expected/index.html b/tests/integration/class-abstract/expected/index.html
@@ -4,10 +4,16 @@ <h1>abstract class</h1>
             <dl class="php class">
     <dt class="sig sig-object php" id="typo3-cms-core-abstracttest">
         <span class="sig-name modifier"><span class="pre">abstract</span></span> <em class="property"><span class="pre">class</span> </em>
-            <span class="sig-prename descclassname"><span class="pre">\TYPO3\CMS\Core\</span></span>
-<span class="sig-name descname"><span class="pre">AbstractTest</span></span> <a class="headerlink" href="#typo3-cms-core-abstracttest" title="Permalink to this definition">¶</a>
+        <span class="sig-name descname">
+    <span class="pre fqn" data-fqn="\TYPO3\CMS\Core\TYPO3\CMS\Core" title="\TYPO3\CMS\Core\TYPO3\CMS\Core">AbstractTest</span>
+</span> <a class="headerlink" href="#typo3-cms-core-abstracttest" title="Permalink to this definition">¶</a>
     </dt>
     <dd>
+                    <dl class="field-list simple">
+                                    <dt class="field-even">Fully qualified name</dt>
+                    <dd class="field-even">
+                        <span class="pre">\TYPO3\CMS\Core\TYPO3\CMS\Core</span>                    </dd>
+                </dl>
 
     <p>Lorem Ipsum Dolor!</p>
 

diff --git a/tests/integration/class-duplicate/expected/index.html b/tests/integration/class-duplicate/expected/index.html
@@ -4,10 +4,16 @@ <h1>final class</h1>
             <dl class="php class">
     <dt class="sig sig-object php" id="typo3-cms-core-test">
         <span class="sig-name modifier"><span class="pre">final</span></span> <em class="property"><span class="pre">class</span> </em>
-            <span class="sig-prename descclassname"><span class="pre">\TYPO3\CMS\Core\</span></span>
-<span class="sig-name descname"><span class="pre">Test</span></span> <a class="headerlink" href="#typo3-cms-core-test" title="Permalink to this definition">¶</a>
+        <span class="sig-name descname">
+    <span class="pre fqn" data-fqn="\TYPO3\CMS\Core\TYPO3\CMS\Core" title="\TYPO3\CMS\Core\TYPO3\CMS\Core">Test</span>
+</span> <a class="headerlink" href="#typo3-cms-core-test" title="Permalink to this definition">¶</a>
     </dt>
     <dd>
+                    <dl class="field-list simple">
+                                    <dt class="field-even">Fully qualified name</dt>
+                    <dd class="field-even">
+                        <span class="pre">\TYPO3\CMS\Core\TYPO3\CMS\Core</span>                    </dd>
+                </dl>
 
     <p>Lorem Ipsum Dolor!</p>
 

diff --git a/tests/integration/class-final-abstract/expected/index.html b/tests/integration/class-final-abstract/expected/index.html
@@ -4,10 +4,16 @@ <h1>abstract final class causes warning</h1>
             <dl class="php class">
     <dt class="sig sig-object php" id="typo3-cms-core-test">
         <span class="sig-name modifier"><span class="pre">abstract</span></span> <span class="sig-name modifier"><span class="pre">final</span></span> <em class="property"><span class="pre">class</span> </em>
-            <span class="sig-prename descclassname"><span class="pre">\TYPO3\CMS\Core\</span></span>
-<span class="sig-name descname"><span class="pre">Test</span></span> <a class="headerlink" href="#typo3-cms-core-test" title="Permalink to this definition">¶</a>
+        <span class="sig-name descname">
+    <span class="pre fqn" data-fqn="\TYPO3\CMS\Core\TYPO3\CMS\Core" title="\TYPO3\CMS\Core\TYPO3\CMS\Core">Test</span>
+</span> <a class="headerlink" href="#typo3-cms-core-test" title="Permalink to this definition">¶</a>
     </dt>
     <dd>
+                    <dl class="field-list simple">
+                                    <dt class="field-even">Fully qualified name</dt>
+                    <dd class="field-even">
+                        <span class="pre">\TYPO3\CMS\Core\TYPO3\CMS\Core</span>                    </dd>
+                </dl>
 
     <p>Lorem Ipsum Dolor!</p>
 

diff --git a/tests/integration/class-final/expected/index.html b/tests/integration/class-final/expected/index.html
@@ -4,10 +4,16 @@ <h1>final class</h1>
             <dl class="php class">
     <dt class="sig sig-object php" id="typo3-cms-core-test">
         <span class="sig-name modifier"><span class="pre">final</span></span> <em class="property"><span class="pre">class</span> </em>
-            <span class="sig-prename descclassname"><span class="pre">\TYPO3\CMS\Core\</span></span>
-<span class="sig-name descname"><span class="pre">Test</span></span> <a class="headerlink" href="#typo3-cms-core-test" title="Permalink to this definition">¶</a>
+        <span class="sig-name descname">
+    <span class="pre fqn" data-fqn="\TYPO3\CMS\Core\TYPO3\CMS\Core" title="\TYPO3\CMS\Core\TYPO3\CMS\Core">Test</span>
+</span> <a class="headerlink" href="#typo3-cms-core-test" title="Permalink to this definition">¶</a>
     </dt>
     <dd>
+                    <dl class="field-list simple">
+                                    <dt class="field-even">Fully qualified name</dt>
+                    <dd class="field-even">
+                        <span class="pre">\TYPO3\CMS\Core\TYPO3\CMS\Core</span>                    </dd>
+                </dl>
 
     <p>Lorem Ipsum Dolor!</p>
 

diff --git a/tests/integration/class-namespace-directive/expected/index.html b/tests/integration/class-namespace-directive/expected/index.html
@@ -4,10 +4,16 @@ <h1>PHP Class with current namespace from directive</h1>
             <dl class="php class">
     <dt class="sig sig-object php" id="typo3-cms-core-testclass">
         <em class="property"><span class="pre">class</span> </em>
-            <span class="sig-prename descclassname"><span class="pre">\TYPO3\CMS\Core\</span></span>
-<span class="sig-name descname"><span class="pre">TestClass</span></span> <a class="headerlink" href="#typo3-cms-core-testclass" title="Permalink to this definition">¶</a>
+        <span class="sig-name descname">
+    <span class="pre fqn" data-fqn="\TYPO3\CMS\Core\TYPO3\CMS\Core" title="\TYPO3\CMS\Core\TYPO3\CMS\Core">TestClass</span>
+</span> <a class="headerlink" href="#typo3-cms-core-testclass" title="Permalink to this definition">¶</a>
     </dt>
     <dd>
+                    <dl class="field-list simple">
+                                    <dt class="field-even">Fully qualified name</dt>
+                    <dd class="field-even">
+                        <span class="pre">\TYPO3\CMS\Core\TYPO3\CMS\Core</span>                    </dd>
+                </dl>
 
     <p>Lorem Ipsum Dolor!</p>
 
@@ -16,10 +22,16 @@ <h1>PHP Class with current namespace from directive</h1>
             <dl class="php class">
     <dt class="sig sig-object php" id="typo3-cms-core-anotherclass">
         <em class="property"><span class="pre">class</span> </em>
-            <span class="sig-prename descclassname"><span class="pre">\TYPO3\CMS\Core\</span></span>
-<span class="sig-name descname"><span class="pre">AnotherClass</span></span> <a class="headerlink" href="#typo3-cms-core-anotherclass" title="Permalink to this definition">¶</a>
+        <span class="sig-name descname">
+    <span class="pre fqn" data-fqn="\TYPO3\CMS\Core\TYPO3\CMS\Core" title="\TYPO3\CMS\Core\TYPO3\CMS\Core">AnotherClass</span>
+</span> <a class="headerlink" href="#typo3-cms-core-anotherclass" title="Permalink to this definition">¶</a>
     </dt>
     <dd>
+                    <dl class="field-list simple">
+                                    <dt class="field-even">Fully qualified name</dt>
+                    <dd class="field-even">
+                        <span class="pre">\TYPO3\CMS\Core\TYPO3\CMS\Core</span>                    </dd>
+                </dl>
 
     <p>Lorem Ipsum Dolor Another!</p>
 
@@ -28,10 +40,16 @@ <h1>PHP Class with current namespace from directive</h1>
             <dl class="php class">
     <dt class="sig sig-object php" id="myvendor-some-namespace-anotherclass">
         <em class="property"><span class="pre">class</span> </em>
-            <span class="sig-prename descclassname"><span class="pre">\MyVendor\Some\Namespace\</span></span>
-<span class="sig-name descname"><span class="pre">AnotherClass</span></span> <a class="headerlink" href="#myvendor-some-namespace-anotherclass" title="Permalink to this definition">¶</a>
+        <span class="sig-name descname">
+    <span class="pre fqn" data-fqn="\MyVendor\Some\Namespace\MyVendor\Some\Namespace" title="\MyVendor\Some\Namespace\MyVendor\Some\Namespace">AnotherClass</span>
+</span> <a class="headerlink" href="#myvendor-some-namespace-anotherclass" title="Permalink to this definition">¶</a>
     </dt>
     <dd>
+                    <dl class="field-list simple">
+                                    <dt class="field-even">Fully qualified name</dt>
+                    <dd class="field-even">
+                        <span class="pre">\MyVendor\Some\Namespace\MyVendor\Some\Namespace</span>                    </dd>
+                </dl>
 
     <p>Lorem Ipsum Dolor Yet Another!</p>
 

diff --git a/tests/integration/class-twice-noindex/expected/index.html b/tests/integration/class-twice-noindex/expected/index.html
@@ -4,10 +4,16 @@ <h1>class listed twice throws warning</h1>
             <dl class="php class">
     <dt class="sig sig-object php" id="typo3-cms-core-test">
         <em class="property"><span class="pre">class</span> </em>
-            <span class="sig-prename descclassname"><span class="pre">\TYPO3\CMS\Core\</span></span>
-<span class="sig-name descname"><span class="pre">Test</span></span> <a class="headerlink" href="#typo3-cms-core-test" title="Permalink to this definition">¶</a>
+        <span class="sig-name descname">
+    <span class="pre fqn" data-fqn="\TYPO3\CMS\Core\TYPO3\CMS\Core" title="\TYPO3\CMS\Core\TYPO3\CMS\Core">Test</span>
+</span> <a class="headerlink" href="#typo3-cms-core-test" title="Permalink to this definition">¶</a>
     </dt>
     <dd>
+                    <dl class="field-list simple">
+                                    <dt class="field-even">Fully qualified name</dt>
+                    <dd class="field-even">
+                        <span class="pre">\TYPO3\CMS\Core\TYPO3\CMS\Core</span>                    </dd>
+                </dl>
 
     <p>Lorem Ipsum Dolor!</p>
 

diff --git a/tests/integration/class-twice-noindex/expected/page2.html b/tests/integration/class-twice-noindex/expected/page2.html
@@ -4,9 +4,15 @@ <h1>class listed twice throws warning</h1>
             <dl class="php class">
     <dt class="sig sig-object php">
         <em class="property"><span class="pre">class</span> </em>
-            <span class="sig-prename descclassname"><span class="pre">\TYPO3\CMS\Core\</span></span>
-<span class="sig-name descname"><span class="pre">Test</span></span>    </dt>
+        <span class="sig-name descname">
+    <span class="pre fqn" data-fqn="\TYPO3\CMS\Core\TYPO3\CMS\Core" title="\TYPO3\CMS\Core\TYPO3\CMS\Core">Test</span>
+</span>    </dt>
     <dd>
+                    <dl class="field-list simple">
+                                    <dt class="field-even">Fully qualified name</dt>
+                    <dd class="field-even">
+                        <span class="pre">\TYPO3\CMS\Core\TYPO3\CMS\Core</span>                    </dd>
+                </dl>
 
     <p>Lorem Ipsum Dolor!</p>
 

diff --git a/tests/integration/class-twice-warning/expected/index.html b/tests/integration/class-twice-warning/expected/index.html
@@ -4,10 +4,16 @@ <h1>class listed twice throws warning</h1>
             <dl class="php class">
     <dt class="sig sig-object php" id="typo3-cms-core-test">
         <em class="property"><span class="pre">class</span> </em>
-            <span class="sig-prename descclassname"><span class="pre">\TYPO3\CMS\Core\</span></span>
-<span class="sig-name descname"><span class="pre">Test</span></span> <a class="headerlink" href="#typo3-cms-core-test" title="Permalink to this definition">¶</a>
+        <span class="sig-name descname">
+    <span class="pre fqn" data-fqn="\TYPO3\CMS\Core\TYPO3\CMS\Core" title="\TYPO3\CMS\Core\TYPO3\CMS\Core">Test</span>
+</span> <a class="headerlink" href="#typo3-cms-core-test" title="Permalink to this definition">¶</a>
     </dt>
     <dd>
+                    <dl class="field-list simple">
+                                    <dt class="field-even">Fully qualified name</dt>
+                    <dd class="field-even">
+                        <span class="pre">\TYPO3\CMS\Core\TYPO3\CMS\Core</span>                    </dd>
+                </dl>
 
     <p>Lorem Ipsum Dolor!</p>
 

diff --git a/tests/integration/class-twice-warning/expected/page2.html b/tests/integration/class-twice-warning/expected/page2.html
@@ -4,10 +4,16 @@ <h1>class listed twice throws warning</h1>
             <dl class="php class">
     <dt class="sig sig-object php" id="typo3-cms-core-test">
         <em class="property"><span class="pre">class</span> </em>
-            <span class="sig-prename descclassname"><span class="pre">\TYPO3\CMS\Core\</span></span>
-<span class="sig-name descname"><span class="pre">Test</span></span> <a class="headerlink" href="#typo3-cms-core-test" title="Permalink to this definition">¶</a>
+        <span class="sig-name descname">
+    <span class="pre fqn" data-fqn="\TYPO3\CMS\Core\TYPO3\CMS\Core" title="\TYPO3\CMS\Core\TYPO3\CMS\Core">Test</span>
+</span> <a class="headerlink" href="#typo3-cms-core-test" title="Permalink to this definition">¶</a>
     </dt>
     <dd>
+                    <dl class="field-list simple">
+                                    <dt class="field-even">Fully qualified name</dt>
+                    <dd class="field-even">
+                        <span class="pre">\TYPO3\CMS\Core\TYPO3\CMS\Core</span>                    </dd>
+                </dl>
 
     <p>Lorem Ipsum Dolor!</p>
 

diff --git a/tests/integration/class-with-const-illegal-modifier-combinations/expected/index.html b/tests/integration/class-with-const-illegal-modifier-combinations/expected/index.html
@@ -4,10 +4,16 @@ <h1>PHP class with constants</h1>
             <dl class="php class">
     <dt class="sig sig-object php" id="chucklefactory-funclass">
         <em class="property"><span class="pre">class</span> </em>
-            <span class="sig-prename descclassname"><span class="pre">\ChuckleFactory\</span></span>
-<span class="sig-name descname"><span class="pre">FunClass</span></span> <a class="headerlink" href="#chucklefactory-funclass" title="Permalink to this definition">¶</a>
+        <span class="sig-name descname">
+    <span class="pre fqn" data-fqn="\ChuckleFactory\ChuckleFactory" title="\ChuckleFactory\ChuckleFactory">FunClass</span>
+</span> <a class="headerlink" href="#chucklefactory-funclass" title="Permalink to this definition">¶</a>
     </dt>
     <dd>
+                    <dl class="field-list simple">
+                                    <dt class="field-even">Fully qualified name</dt>
+                    <dd class="field-even">
+                        <span class="pre">\ChuckleFactory\ChuckleFactory</span>                    </dd>
+                </dl>
 
     <p>Where Fun Knows No Bounds!</p>
 <dl class="php const">