Update phpdoc and simplify code. (#86)

src/Attribute/Aria/HasAriaControls.php

@@ -5,20 +5,27 @@
 namespace PHPForge\Html\Attribute\Aria;
 
 /**
- * Is used by widgets which have an aria-controls attribute.
+ * Is used by widgets that require the aria-controls attribute.
  */
 trait HasAriaControls
 {
     /**
-     * The global aria-controls property identifies the element (or elements) whose contents or presence are controlled
-     * by the element on which this attribute is set.
+     * Set the aria-controls attribute, which identifies the element(s) whose contents or presence are controlled
+     * by the current element.
+     *
+     * The aria-controls attribute is used in WAI-ARIA to define a relationship between a controller element and
+     * controlled elements, typically used for accessibility in web applications.
+     *
+     * @param string $value IDs of the controlled element(s) separated by spaces.
+     *
+     * @return static A new instance or clone of the current object with the aria-controls attribute set.
      *
      * @link https://www.w3.org/TR/wai-aria-1.1/#aria-controls
      */
-    public function ariaControls(string $ariaControls): self
+    public function ariaControls(string $value): static
     {
         $new = clone $this;
-        $new->attributes['aria-controls'] = $ariaControls;
+        $new->attributes['aria-controls'] = $value;
 
         return $new;
     }

src/Attribute/Aria/HasAriaDescribedBy.php

@@ -5,17 +5,22 @@
 namespace PHPForge\Html\Attribute\Aria;
 
 /**
- * Is used by widgets which have an aria-describedby attribute.
+ * Is used by widgets that require the aria-describedby attribute.
  */
 trait HasAriaDescribedBy
 {
     /**
-     * Returns a new instance specifying the element (or elements) that describes the element on which the attribute is
-     * set.
+     * Set the aria-describedby attribute, which identifies the element(s) that describe the current element.
      *
-     * @param string $value The value of the aria-describedby attribute.
+     * The aria-describedby attribute is used in WAI-ARIA to provide a relationship between an element and its
+     * descriptive elements. This helps screen readers and other assistive technologies provide additional context
+     * about the element.
      *
-     * @link https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby
+     * @param string $value IDs of the descriptive element(s) separated by spaces.
+     *
+     * @return static A new instance or clone of the current object with the aria-describedby attribute set.
+     *
+     * @link https://www.w3.org/TR/wai-aria-1.1/#aria-describedby
      */
     public function ariaDescribedBy(string $value): static
     {

src/Attribute/Aria/HasAriaDisabled.php

@@ -5,20 +5,26 @@
 namespace PHPForge\Html\Attribute\Aria;
 
 /**
- * Is used by widgets which have an aria-disabled attribute.
+ * Is used by widgets that require the aria-disabled attribute.
  */
 trait HasAriaDisabled
 {
     /**
-     * The aria-disabled state indicates that the element is perceivable but disabled, so it is not editable or
-     * otherwise operable.
+     * Set the aria-disabled attribute, indicating whether the element is perceivable but disabled for interaction.
+     *
+     * The aria-disabled attribute is used in WAI-ARIA to convey that an element is not currently operable or editable,
+     * typically to users of assistive technologies.
+     *
+     * @param string $value The value for the aria-disabled attribute ("true" or "false").
+     *
+     * @return static A new instance or clone of the current object with the aria-disabled attribute set.
      *
      * @link https://www.w3.org/TR/wai-aria-1.1/#aria-disabled
      */
-    public function ariaDisabled(string $ariaDisabled): self
+    public function ariaDisabled(string $value): static
     {
         $new = clone $this;
-        $new->attributes['aria-disabled'] = $ariaDisabled;
+        $new->attributes['aria-disabled'] = $value;
 
         return $new;
     }

src/Attribute/Aria/HasAriaExpanded.php

@@ -5,20 +5,26 @@
 namespace PHPForge\Html\Attribute\Aria;
 
 /**
- * Is used by widgets which have an aria-expanded attribute.
+ * Is used by widgets that require the aria-expanded attribute.
  */
 trait HasAriaExpanded
 {
     /**
-     * The aria-expanded attribute is set on an element to indicate if a control is expanded or collapsed, and whether
-     * or not the controlled elements are displayed or hidden.
+     * Set the aria-expanded attribute, indicating whether the element is currently expanded or collapsed.
+     *
+     * The aria-expanded attribute is used in WAI-ARIA to convey the current expansion state of collapsible elements,
+     * typically to users of assistive technologies.
+     *
+     * @param string $value The value for the aria-expanded attribute ("true" or "false").
+     *
+     * @return static A new instance or clone of the current object with the aria-expanded attribute set.
      *
      * @link https://www.w3.org/TR/wai-aria-1.1/#aria-expanded
      */
-    public function ariaExpanded(string $ariaExpanded): static
+    public function ariaExpanded(string $value): static
     {
         $new = clone $this;
-        $new->attributes['aria-expanded'] = $ariaExpanded;
+        $new->attributes['aria-expanded'] = $value;
 
         return $new;
     }

src/Attribute/Aria/HasAriaLabel.php

@@ -5,16 +5,18 @@
 namespace PHPForge\Html\Attribute\Aria;
 
 /**
- * Is used by widgets which have an aria-label attribute.
+ * Is used by widgets which require an aria-label attribute.
  */
 trait HasAriaLabel
 {
     /**
-     * Returns a new instance specifying a string value that labels an interactive element.
+     * Set the aria-label attribute, is a string that labels the current interactive element.
      *
      * @param string $value The value of the aria-label attribute.
      *
-     * @link https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label
+     * @return static A new instance of the current class with the specified aria-label attribute.
+     *
+     * @link https://www.w3.org/TR/wai-aria/#aria-label
      */
     public function ariaLabel(string $value): static
     {

src/Attribute/Aria/HasRole.php

@@ -5,20 +5,24 @@
 namespace PHPForge\Html\Attribute\Aria;
 
 /**
- * Is used by widgets which have an role attribute.
+ * Is used by widgets which require an role attribute.
  */
 trait HasRole
 {
     /**
+     * Set the ARIA role for the element.
+     *
      * ARIA roles provide semantic meaning to content, allowing screen readers and other tools to present and support
      * interaction with an object in a way that is consistent with user expectations of that type of object.
      *
+     * @return static A new instance of the current class with the specified role attribute.
+     *
      * @link https://www.w3.org/TR/wai-aria-1.1/#role_definitions
      */
-    public function role(string $role): self
+    public function role(string $value): self
     {
         $new = clone $this;
-        $new->attributes['role'] = $role;
+        $new->attributes['role'] = $value;
 
         return $new;
     }

src/Attribute/CanBeAutofocus.php

@@ -5,15 +5,17 @@
 namespace PHPForge\Html\Attribute;
 
 /**
- * Is used by widgets which have an autofocus attribute.
+ * Is used by widgets that implement the autofocus method.
  */
 trait CanBeAutofocus
 {
     /**
-     * Returns a new instance specifying the focus on the control (put cursor into it) when the page loads.
+     * Set the focus on the control (put cursor into it) when the page loads.
      *
      * Only one form element could be in focus at the same time.
      *
+     * @return static A new instance of the current class with the specified autofocus value.
+     *
      * @link https://www.w3.org/TR/html52/sec-forms.html#autofocusing-a-form-control-the-autofocus-attribute
      */
     public function autofocus(): static

src/Attribute/CanBeHidden.php

@@ -5,13 +5,15 @@
 namespace PHPForge\Html\Attribute;
 
 /**
- * Is used by widgets which have an hidden attribute.
+ * Is used by widgets that implement the hidden method.
  */
 trait CanBeHidden
 {
     /**
-     * Returns a new instance specifying that the hidden global attribute is an enumerated attribute indicating that the
-     * browser should not render the contents of the element.
+     * Set the hidden global attribute is an enumerated attribute indicating that the browser should not render the
+     * contents of the element.
+     *
+     * @return static A new instance of the current class with the specified hidden value.
      *
      * @link https://html.spec.whatwg.org/multipage/interaction.html#the-hidden-attribute
      */

src/Attribute/Custom/HasActiveClass.php

@@ -5,16 +5,18 @@
 namespace PHPForge\Html\Attribute\Custom;
 
 /**
- * Is used by widgets which have an active class property.
+ * Is used by widgets which implement the activeClass method.
  */
 trait HasActiveClass
 {
     protected string $activeClass = 'active';
 
     /**
-     * Returns a new instance specifying the `CSS` class to be appended to the active class.
+     * Set the `CSS` class to be appended to the active class.
      *
      * @param string $value The `CSS` class to be appended to the active class.
+     *
+     * @return static A new instance of the current class with the specified active class.
      */
     public function activeClass(string $value): static
     {

src/Attribute/Custom/HasAttributes.php

@@ -7,17 +7,19 @@
 use function array_merge;
 
 /**
- * Is used by widgets which have an attributes.
+ * Is used by widgets which implement the attributes method.
  *
  * @link https://www.w3.org/TR/html52/dom.html#global-attributes
  * @link https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes
  */
 trait HasAttributes
 {
     /**
-     * Returns a new instance specifying the `HTML` attributes.
+     * Set the `HTML` attributes.
      *
      * @param array $values Attribute values indexed by attribute names.
+     *
+     * @return static A new instance of the current class with the specified attributes.
      */
     public function attributes(array $values): static
     {