fix(docs): Refactor attribute documentation in traits. (#84)

Author: terabytesoftw

CHANGELOG.md

@@ -54,6 +54,7 @@
 - Bug #81: Migrate mixin attribute setters and tests to the simplified API (@terabytesoftw)
 - Bug #82: Update `ui-awesome/html-helper` requirement to use stable version constraint `^0.7` in `composer.json` (@terabytesoftw)
 - Enh #83: Enhance `HasAria`, `HasData`, and `HasEvents` traits to support prefix attributes `aria-`, `data-`, and `on` (@terabytesoftw)
+- Bug #84: Refactor attribute documentation in traits (@terabytesoftw)
 
 ## 0.5.2 January 29, 2026
 

src/Element/HasAlt.php

@@ -11,7 +11,7 @@
 /**
  * Provides an immutable API for the `alt` attribute.
  *
- * @method static setAttribute(string|UnitEnum $key, mixed $value) Adds an attribute and returns a new instance.
+ * @mixin \UIAwesome\Html\Mixin\HasAttributes
  * @link https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/img#alt
  *
  * @copyright Copyright (C) 2025 Terabytesoftw.
@@ -22,17 +22,17 @@ trait HasAlt
     /**
      * Sets the `alt` attribute.
      *
-     * @param string|Stringable|UnitEnum|null $value Alternative text for the element, or `null` to remove the
-     * attribute.
-     *
-     * @return static New instance with the updated `alt` attribute.
-     *
      * Usage example:
      * ```php
      * $element->alt('A penguin on a beach.');
      * $element->alt('');
      * $element->alt(null);
      * ```
+     *
+     * @param string|Stringable|UnitEnum|null $value Alternative text for the element, or `null` to remove the
+     * attribute.
+     *
+     * @return static New instance with the updated `alt` attribute.
      */
     public function alt(string|Stringable|UnitEnum|null $value): static
     {

src/Element/HasDecoding.php

@@ -13,7 +13,7 @@
 /**
  * Provides an immutable API for the HTML and SVG `decoding` attribute.
  *
- * @method static setAttribute(string|UnitEnum $key, mixed $value) Adds an attribute and returns a new instance.
+ * @mixin \UIAwesome\Html\Mixin\HasAttributes
  * @link https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/img#decoding
  * @link https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Attribute/decoding
  *
@@ -25,6 +25,13 @@ trait HasDecoding
     /**
      * Sets the `decoding` attribute.
      *
+     * Usage example:
+     * ```php
+     * $element->decoding('async');
+     * $element->decoding(Decoding::ASYNC);
+     * $element->decoding(null);
+     * ```
+     *
      * @param string|Stringable|UnitEnum|null $value Decoding hint value. Use `async`, `sync`, or `auto`, or `null` to
      * remove the attribute.
      *
@@ -33,13 +40,6 @@ trait HasDecoding
      * @return static New instance with the updated `decoding` attribute.
      *
      * {@see Decoding} for predefined enum values.
-     *
-     * Usage example:
-     * ```php
-     * $element->decoding('async');
-     * $element->decoding(Decoding::ASYNC);
-     * $element->decoding(null);
-     * ```
      */
     public function decoding(string|Stringable|UnitEnum|null $value): static
     {

src/Element/HasHeight.php

@@ -11,7 +11,7 @@
 /**
  * Provides an immutable API for the `height` attribute.
  *
- * @method static setAttribute(string|UnitEnum $key, mixed $value) Adds an attribute and returns a new instance.
+ * @mixin \UIAwesome\Html\Mixin\HasAttributes
  * @link https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/img#height
  * @link https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Attribute/height
  *
@@ -23,17 +23,17 @@ trait HasHeight
     /**
      * Sets the `height` attribute.
      *
-     * @param int|string|Stringable|UnitEnum|null $value Height value in pixels or CSS units, or `null` to remove the
-     * attribute.
-     *
-     * @return static New instance with the updated `height` attribute.
-     *
      * Usage example:
      * ```php
      * $element->height(200);
      * $element->height('50%');
      * $element->height('auto');
      * ```
+     *
+     * @param int|string|Stringable|UnitEnum|null $value Height value in pixels or CSS units, or `null` to remove the
+     * attribute.
+     *
+     * @return static New instance with the updated `height` attribute.
      */
     public function height(int|string|Stringable|UnitEnum|null $value): static
     {

src/Element/HasHref.php

@@ -11,7 +11,7 @@
 /**
  * Provides an immutable API for the HTML and SVG `href` attribute.
  *
- * @method static setAttribute(string|UnitEnum $key, mixed $value) Adds an attribute and returns a new instance.
+ * @mixin \UIAwesome\Html\Mixin\HasAttributes
  * @link https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/a#href
  * @link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/href
  *
@@ -23,17 +23,17 @@ trait HasHref
     /**
      * Sets the `href` attribute.
      *
-     * @param string|Stringable|UnitEnum|null $value URL, path, or fragment, or `null` to remove the attribute.
-     *
-     * @return static New instance with the updated `href` attribute.
-     *
      * Usage example:
      * ```php
      * $element->href('https://example.com/page');
      * $element->href('/about');
      * $element->href('#section');
      * $element->href(null);
      * ```
+     *
+     * @param string|Stringable|UnitEnum|null $value URL, path, or fragment, or `null` to remove the attribute.
+     *
+     * @return static New instance with the updated `href` attribute.
      */
     public function href(string|Stringable|UnitEnum|null $value): static
     {

src/Element/HasLoading.php

@@ -13,7 +13,7 @@
 /**
  * Provides an immutable API for the `loading` attribute.
  *
- * @method static setAttribute(string|UnitEnum $key, mixed $value) Adds an attribute and returns a new instance.
+ * @mixin \UIAwesome\Html\Mixin\HasAttributes
  * @link https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe#loading
  * @link https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/img#loading
  *
@@ -25,6 +25,13 @@ trait HasLoading
     /**
      * Sets the `loading` attribute.
      *
+     * Usage example:
+     * ```php
+     * $element->loading('lazy');
+     * $element->loading(Loading::LAZY);
+     * $element->loading(null);
+     * ```
+     *
      * @param string|Stringable|UnitEnum|null $value Loading strategy (`eager` or `lazy`), or `null` to remove the
      * attribute.
      *
@@ -33,13 +40,6 @@ trait HasLoading
      * @return static New instance with the updated `loading` attribute.
      *
      * {@see Loading} for predefined enum values.
-     *
-     * Usage example:
-     * ```php
-     * $element->loading('lazy');
-     * $element->loading(Loading::LAZY);
-     * $element->loading(null);
-     * ```
      */
     public function loading(string|Stringable|UnitEnum|null $value): static
     {

src/Element/HasPopoverTarget.php

@@ -11,9 +11,7 @@
 /**
  * Provides an immutable API for the `popovertarget` attribute.
  *
- * @method static setAttribute(string|UnitEnum $key, mixed $value) Adds an attribute and returns a new instance.
- * {@see \UIAwesome\Html\Mixin\HasAttributes} for managing the underlying attributes array.
- *
+ * @mixin \UIAwesome\Html\Mixin\HasAttributes
  * @link https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/popovertarget
  *
  * @copyright Copyright (C) 2026 Terabytesoftw.

src/Element/HasPopoverTargetAction.php

@@ -13,9 +13,7 @@
 /**
  * Provides an immutable API for the `popovertargetaction` attribute.
  *
- * @method static setAttribute(string|UnitEnum $key, mixed $value) Adds an attribute and returns a new instance.
- * {@see \UIAwesome\Html\Mixin\HasAttributes} for managing the underlying attributes array.
- *
+ * @mixin \UIAwesome\Html\Mixin\HasAttributes
  * @link https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/button#popovertargetaction
  *
  * @copyright Copyright (C) 2026 Terabytesoftw.

src/Element/HasReferrerpolicy.php

@@ -13,7 +13,7 @@
 /**
  * Provides an immutable API for the `referrerpolicy` attribute.
  *
- * @method static setAttribute(string|UnitEnum $key, mixed $value) Adds an attribute and returns a new instance.
+ * @mixin \UIAwesome\Html\Mixin\HasAttributes
  * @link https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/a#referrerpolicy
  * @link https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/area#href
  * @link https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe#referrerpolicy
@@ -29,20 +29,20 @@ trait HasReferrerpolicy
     /**
      * Sets the `referrerpolicy` attribute.
      *
+     * Usage example:
+     * ```php
+     * $element->referrerpolicy('origin');
+     * $element->referrerpolicy(Referrerpolicy::NO_REFERRER);
+     * $element->referrerpolicy(null);
+     * ```
+     *
      * @param string|Stringable|UnitEnum|null $value Referrer policy token, or `null` to remove the attribute.
      *
      * @throws InvalidArgumentException If the value is not valid.
      *
      * @return static New instance with the updated `referrerpolicy` attribute.
      *
      * {@see Referrerpolicy} for predefined enum values.
-     *
-     * Usage example:
-     * ```php
-     * $element->referrerpolicy('origin');
-     * $element->referrerpolicy(Referrerpolicy::NO_REFERRER);
-     * $element->referrerpolicy(null);
-     * ```
      */
     public function referrerpolicy(string|Stringable|UnitEnum|null $value): static
     {

src/Element/HasSrc.php

@@ -11,7 +11,7 @@
 /**
  * Provides an immutable API for the `src` attribute.
  *
- * @method static setAttribute(string|UnitEnum $key, mixed $value) Adds an attribute and returns a new instance.
+ * @mixin \UIAwesome\Html\Mixin\HasAttributes
  * @link https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/img#src
  *
  * @copyright Copyright (C) 2025 Terabytesoftw.
@@ -22,16 +22,16 @@ trait HasSrc
     /**
      * Sets the `src` attribute.
      *
-     * @param string|Stringable|UnitEnum|null $value Image source URL or path, or `null` to remove the attribute.
-     *
-     * @return static New instance with the updated `src` attribute.
-     *
      * Usage example:
      * ```php
      * $element->src('https://example.com/image.png');
      * $element->src('images/photo.jpg');
      * $element->src(null);
      * ```
+     *
+     * @param string|Stringable|UnitEnum|null $value Image source URL or path, or `null` to remove the attribute.
+     *
+     * @return static New instance with the updated `src` attribute.
      */
     public function src(string|Stringable|UnitEnum|null $value): static
     {