Merge pull request #3719 from phpDocumentor/feature/attribute-ui-impr…

…ovements

Feat: improvements on display of used attributes per element

config/stages.yaml

@@ -17,36 +17,44 @@ parameters:
       - 'properties'
       - 'methods'
       - 'usedTraits'
+      - 'attributes'
     'phpDocumentor\Descriptor\InterfaceDescriptor':
       - 'tags'
       - 'parent'
       - 'constants'
       - 'methods'
+      - 'attributes'
     'phpDocumentor\Descriptor\TraitDescriptor':
       - 'tags'
       - 'properties'
       - 'methods'
       - 'usedTraits'
+      - 'attributes'
     'phpDocumentor\Descriptor\EnumDescriptor':
       - 'tags'
       - 'interfaces'
       - 'cases'
       - 'methods'
       - 'usedTraits'
+      - 'attributes'
     'phpDocumentor\Descriptor\FunctionDescriptor':
       - 'tags'
       - 'arguments'
     'phpDocumentor\Descriptor\MethodDescriptor':
       - 'tags'
       - 'arguments'
+      - 'attributes'
     'phpDocumentor\Descriptor\ArgumentDescriptor':
       - 'type'
     'phpDocumentor\Descriptor\PropertyDescriptor':
       - 'tags'
       - 'type'
+      - 'attributes'
     'phpDocumentor\Descriptor\ConstantDescriptor':
       - 'tags'
       - 'type'
+      - 'attributes'
+    'phpDocumentor\Descriptor\AttributeDescriptor': ['attribute']
     'phpDocumentor\Descriptor\Tag\ParamDescriptor': ['type']
     'phpDocumentor\Descriptor\Tag\VarDescriptor': ['type']
     'phpDocumentor\Descriptor\Tag\ReturnDescriptor': ['type']

data/templates/default/class.html.twig

@@ -7,8 +7,6 @@
         {{ include('components/class-title.html.twig') }}
         {{ include('components/element-found-in.html.twig') }}
         {{ include('components/element-header.html.twig') }}
-
-        {{ include('components/attributes.html.twig') }}
         {{ include('components/constants.html.twig') }}
         {{ include('components/properties.html.twig') }}
         {{ include('components/methods.html.twig') }}

data/templates/default/components/attribute.html.twig

@@ -1,10 +1,10 @@
-<article
-        class="
-            phpdocumentor-element
-            -attribute
-        "
->
-    <h4 class="phpdocumentor-element__name">
-        #[{{ attribute.name }}]
-    </h4>
-</article>
+<dl class="phpdocumentor-argument-list">
+    <dt class="phpdocumentor-argument-list__entry">
+        #[{{ attribute.attribute | route('class:short') }}]
+    </dt>
+    {% for argument in attribute.arguments %}
+    <dd class="phpdocumentor-argument-list__entry">
+        {% if argument.name %}${{ argument.name }}: {% endif %}{{ argument.value }}
+    </dd>
+    {% endfor %}
+</dl>

data/templates/default/components/attributes.html.twig

@@ -2,10 +2,9 @@
 
 {% if attributes is not empty %}
     <section class="phpdocumentor-attributes">
-        <h3 class="phpdocumentor-elements__header" id="attributes">
-            Attributes
-            {{ include('components/headerlink.html.twig', {'on': node, 'at': 'attributes'}, with_context = false) }}
-        </h3>
+        <h5 class="phpdocumentor-elements__header" id="attributes">
+            Attributes {{ include('components/headerlink.html.twig', {'on': node, 'at': 'attributes'}, with_context = false) }}
+        </h5>
         {% for attribute in attributes %}
             {% include 'components/attribute.html.twig' %}
         {% endfor %}

data/templates/default/components/constant.html.twig

@@ -11,4 +11,5 @@
     {{ include('components/description.html.twig', {'node': constant}) }}
     {{ include('components/description.html.twig', {'node': constant.var[0]}) }}
     {{ include ('components/tags.html.twig', {'node': constant}) }}
+    {{ include('components/attributes.html.twig' , {'node': constant}) }}
 </article>

data/templates/default/components/element-header.html.twig

@@ -1,5 +1,6 @@
 {{ include('components/summary.html.twig') }}
 {{ include('components/description.html.twig') }}
 {{ include('components/tags.html.twig', {node: node}) }}
+{{ include('components/attributes.html.twig') }}
 
 {{ include ('components/table-of-contents.html.twig') }}

data/templates/default/components/enum-case.html.twig

@@ -13,4 +13,5 @@
     {{ include('components/description.html.twig', {'node': case}) }}
     {{ include('components/description.html.twig', {'node': case.var[0]}) }}
     {{ include ('components/tags.html.twig', {'node': case}) }}
+    {{ include('components/attributes.html.twig' , {'node': case}) }}
 </article>

data/templates/default/components/method.html.twig

@@ -23,5 +23,6 @@
     {{ include('components/description.html.twig', {'node': method}) }}
     {{ include('components/method-arguments.html.twig', {'node': method}) }}
     {{ include('components/tags.html.twig', {'node': method }) }}
+    {{ include('components/attributes.html.twig' , {'node': method}) }}
     {{ include('components/method-response.html.twig', {'node': method}) }}
 </article>

data/templates/default/components/property.html.twig

@@ -23,4 +23,5 @@
     {{ include('components/description.html.twig', {'node': property}) }}
     {{ include('components/description.html.twig', {'node': property.var[0]}) }}
     {{ include('components/tags.html.twig', {'node': property}) }}
+    {{ include('components/attributes.html.twig' , {'node': property}) }}
 </article>

data/templates/default/enum.html.twig

@@ -8,7 +8,6 @@
         {{ include('components/element-found-in.html.twig') }}
         {{ include('components/element-header.html.twig') }}
 
-        {{ include('components/attributes.html.twig') }}
         {{ include('components/enum-cases.html.twig') }}
         {{ include('components/methods.html.twig') }}
         {{ include('components/source-modal.html.twig') }}

data/templates/default/interface.html.twig

@@ -8,7 +8,6 @@
         {{ include('components/element-found-in.html.twig') }}
         {{ include('components/element-header.html.twig') }}
 
-        {{ include('components/attributes.html.twig') }}
         {{ include('components/constants.html.twig') }}
         {{ include('components/methods.html.twig') }}
         {{ include('components/source-modal.html.twig') }}

data/templates/default/trait.html.twig

@@ -8,7 +8,6 @@
         {{ include('components/element-found-in.html.twig') }}
         {{ include('components/element-header.html.twig') }}
 
-        {{ include('components/attributes.html.twig') }}
         {{ include('components/constants.html.twig') }}
         {{ include('components/properties.html.twig') }}
         {{ include('components/methods.html.twig') }}

src/phpDocumentor/Compiler/ApiDocumentation/Linker/Linker.php

@@ -56,7 +56,7 @@
 #[Stage(
     'phpdoc.pipeline.api_documentation.compile',
     10000,
-    'Replace textual FQCNs with object aliases',
+    description: 'Replace textual FQCNs with object aliases',
 )]
 final class Linker extends ApiDocumentationPass
 {

src/phpDocumentor/Descriptor/AttributeDescriptor.php

@@ -5,9 +5,11 @@
 namespace phpDocumentor\Descriptor;
 
 use phpDocumentor\Descriptor\Interfaces\AttributeInterface;
+use phpDocumentor\Descriptor\Interfaces\ClassInterface;
 use phpDocumentor\Descriptor\Traits\HasDescription;
 use phpDocumentor\Descriptor\Traits\HasFqsen;
 use phpDocumentor\Descriptor\Traits\HasName;
+use phpDocumentor\Reflection\Fqsen;
 use Stringable;
 
 final class AttributeDescriptor implements Descriptor, Stringable, AttributeInterface
@@ -16,8 +18,47 @@ final class AttributeDescriptor implements Descriptor, Stringable, AttributeInte
     use HasDescription;
     use HasFqsen;
 
+    /** @var Collection<ValueObjects\CallArgument> */
+    private Collection $arguments;
+    private ClassInterface|null $attributeClass = null;
+
+    public function __construct()
+    {
+        $this->arguments = Collection::fromClassString(ValueObjects\CallArgument::class);
+    }
+
+    public function getAttribute(): ClassInterface|Fqsen|null
+    {
+        if ($this->attributeClass !== null) {
+            return $this->attributeClass;
+        }
+
+        return $this->fqsen;
+    }
+
+    public function setAttribute(ClassInterface|null $attributeClass): void
+    {
+        $this->attributeClass = $attributeClass;
+    }
+
     public function __toString(): string
     {
         return $this->getName();
     }
+
+    public function addArgument(ValueObjects\CallArgument $argument): void
+    {
+        $this->arguments->add($argument);
+    }
+
+    /** @return Collection<ValueObjects\CallArgument> */
+    public function getArguments(): Collection
+    {
+        return $this->arguments;
+    }
+
+    public function hasArguments(): bool
+    {
+        return $this->arguments->count() > 0;
+    }
 }

src/phpDocumentor/Descriptor/Builder/Reflector/FunctionAssembler.php

@@ -49,7 +49,7 @@ public function __construct(private readonly ArgumentAssembler $argumentAssemble
      *
      * @param Function_ $data
      */
-    public function create(object $data): FunctionInterface
+    public function buildDescriptor(object $data): FunctionInterface
     {
         $functionDescriptor = new FunctionDescriptor();
 

src/phpDocumentor/Descriptor/Builder/Reflector/MethodAssembler.php

@@ -48,7 +48,7 @@ public function __construct(private readonly ArgumentAssembler $argumentAssemble
      *
      * @param Method $data
      */
-    public function create(object $data): MethodInterface
+    public function buildDescriptor(object $data): MethodInterface
     {
         $methodDescriptor = new MethodDescriptor();
         $methodDescriptor->setNamespace(

src/phpDocumentor/Descriptor/Builder/Reflector/Reducer/AttributeReducer.php

@@ -8,6 +8,7 @@
 use phpDocumentor\Descriptor\Builder\AssemblerReducer;
 use phpDocumentor\Descriptor\Descriptor;
 use phpDocumentor\Descriptor\Interfaces\AttributedInterface;
+use phpDocumentor\Descriptor\ValueObjects\CallArgument;
 use phpDocumentor\Reflection\Php\AttributeContainer;
 
 final class AttributeReducer implements AssemblerReducer
@@ -26,6 +27,10 @@ public function create(object $data, Descriptor|null $descriptor = null): Descri
             $attributeDescriptor = new AttributeDescriptor();
             $attributeDescriptor->setName($attribute->getName());
             $attributeDescriptor->setFullyQualifiedStructuralElementName($attribute->getFqsen());
+            foreach ($attribute->getArguments() as $argument) {
+                $attributeDescriptor->addArgument(new CallArgument($argument->getValue(), $argument->getName()));
+            }
+
             $descriptor->addAttribute($attributeDescriptor);
         }
 

src/phpDocumentor/Descriptor/Interfaces/AttributeInterface.php

@@ -4,6 +4,8 @@
 
 namespace phpDocumentor\Descriptor\Interfaces;
 
+use phpDocumentor\Descriptor\Collection;
+use phpDocumentor\Descriptor\ValueObjects\CallArgument;
 use phpDocumentor\Reflection\Fqsen;
 
 interface AttributeInterface
@@ -19,4 +21,11 @@ public function setFullyQualifiedStructuralElementName(Fqsen $name): void;
      * Returns the Fully Qualified Structural Element Name (FQSEN) for this element.
      */
     public function getFullyQualifiedStructuralElementName(): Fqsen|null;
+
+    public function addArgument(CallArgument $argument): void;
+
+    /** @return Collection<CallArgument> */
+    public function getArguments(): Collection;
+
+    public function hasArguments(): bool;
 }

src/phpDocumentor/Descriptor/Interfaces/AttributedInterface.php

@@ -11,8 +11,5 @@ interface AttributedInterface
     /** @return Collection<AttributeInterface> */
     public function getAttributes(): Collection;
 
-    /** @return Collection<AttributeInterface> */
-    public function getInheritedAttributes(): Collection;
-
     public function addAttribute(AttributeInterface $attribute): void;
 }

src/phpDocumentor/Descriptor/Interfaces/MethodInterface.php

@@ -20,7 +20,12 @@
 /**
  * Describes the public interface of the description for a method.
  */
-interface MethodInterface extends ElementInterface, TypeInterface, InheritsFromElement, ChildInterface
+interface MethodInterface extends
+    ElementInterface,
+    TypeInterface,
+    InheritsFromElement,
+    ChildInterface,
+    AttributedInterface
 {
     public function setAbstract(bool $abstract): void;
 

src/phpDocumentor/Descriptor/Interfaces/PropertyInterface.php

@@ -20,7 +20,7 @@
 /**
  * Descriptor representing a property on a class or trait.
  */
-interface PropertyInterface extends ElementInterface, TypeInterface, ChildInterface, IsTyped
+interface PropertyInterface extends ElementInterface, TypeInterface, ChildInterface, IsTyped, AttributedInterface
 {
     /**
      * Returns true when this property is intended to be read-only.

src/phpDocumentor/Descriptor/MethodDescriptor.php

@@ -41,8 +41,7 @@
  */
 class MethodDescriptor extends DescriptorAbstract implements
     Interfaces\MethodInterface,
-    Interfaces\VisibilityInterface,
-    Interfaces\AttributedInterface
+    Interfaces\VisibilityInterface
 {
     use CanBeFinal;
     use CanBeAbstract;

src/phpDocumentor/Descriptor/PropertyDescriptor.php

@@ -37,6 +37,7 @@ class PropertyDescriptor extends DescriptorAbstract implements
     use Traits\HasVisibility;
     use Traits\CanHaveAType;
     use Traits\CanHaveADefaultValue;
+    use Traits\HasAttributes;
 
     /** @var ClassInterface|TraitInterface|null $parent */
     protected ElementInterface|null $parent = null;

src/phpDocumentor/Descriptor/Traits/HasAttributes.php

@@ -5,9 +5,7 @@
 namespace phpDocumentor\Descriptor\Traits;
 
 use phpDocumentor\Descriptor\Collection;
-use phpDocumentor\Descriptor\Interfaces\AttributedInterface;
 use phpDocumentor\Descriptor\Interfaces\AttributeInterface;
-use phpDocumentor\Descriptor\Interfaces\ChildInterface;
 
 trait HasAttributes
 {
@@ -33,21 +31,4 @@ public function getAttributes(): Collection
 
         return $this->attributes;
     }
-
-    /** @return Collection<AttributeInterface> */
-    public function getInheritedAttributes(): Collection
-    {
-        if ($this instanceof ChildInterface === false) {
-            return Collection::fromInterfaceString(AttributeInterface::class);
-        }
-
-        $parent = $this->getParent();
-        if ($parent instanceof AttributedInterface === false) {
-            return $this->getAttributes();
-        }
-
-        return $this->getAttributes()->merge(
-            $parent->getInheritedAttributes(),
-        );
-    }
 }

src/phpDocumentor/Descriptor/ValueObjects/CallArgument.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Descriptor\ValueObjects;
+
+final class CallArgument
+{
+    public function __construct(private readonly string $value, private readonly string|null $name)
+    {
+    }
+
+    public function getValue(): string
+    {
+        return $this->value;
+    }
+
+    public function getName(): string|null
+    {
+        return $this->name;
+    }
+}

src/phpDocumentor/Transformer/Writer/Twig/Extension.php

@@ -316,10 +316,6 @@ static function (DescriptorAbstract $descriptor): Collection {
                         $attributes = $attributes->merge($descriptor->getAttributes());
                     }
 
-                    if (method_exists($descriptor, 'getInheritedAttributes')) {
-                        $attributes = $attributes->merge($descriptor->getInheritedAttributes());
-                    }
-
                     return $attributes;
                 },
             ),

tests/unit/phpDocumentor/Descriptor/AttributedTestTrait.php

@@ -20,6 +20,7 @@ public function testAddAttribute(): void
 
     public function testGetInheritedAttributesReturnsAttributesFromParent(): void
     {
+        $this->markTestSkipped('Not implemented yet.');
         $parent = $this->getParent();
         $expected = 0;
         if ($parent !== null) {