[CLEANUP] Tidy up comments in RuleSet

src/RuleSet/RuleSet.php

@@ -32,8 +32,8 @@ class RuleSet implements CSSElement, CSSListItem, Positionable, RuleContainer
     use Position;
 
     /**
-     * the rules in this rule set, using the property name as the key,
-     * with potentially multiple rules per property name.
+     * the declarations in this rule set, using the property name as the key,
+     * with potentially multiple declarations per property name.
      *
      * @var array<string, array<int<0, max>, Declaration>>
      */
@@ -171,16 +171,16 @@ public function addRule(Declaration $declarationToAdd, ?Declaration $sibling = n
     }
 
     /**
-     * Returns all rules matching the given rule name
+     * Returns all declarations matching the given property name
      *
      * @example $ruleSet->getRules('font') // returns array(0 => $declaration, …) or array().
      *
      * @example $ruleSet->getRules('font-')
-     *          //returns an array of all rules either beginning with font- or matching font.
+     *          //returns an array of all declarations either beginning with font- or matching font.
      *
      * @param string|null $searchPattern
-     *        Pattern to search for. If null, returns all rules.
-     *        If the pattern ends with a dash, all rules starting with the pattern are returned
+     *        Pattern to search for. If null, returns all declarations.
+     *        If the pattern ends with a dash, all declarations starting with the pattern are returned
      *        as well as one matching the pattern with the dash excluded.
      *
      * @return array<int<0, max>, Declaration>
@@ -189,8 +189,10 @@ public function getRules(?string $searchPattern = null): array
     {
         $result = [];
         foreach ($this->declarations as $propertyName => $declarations) {
-            // Either no search rule is given or the search rule matches the found rule exactly
-            // or the search rule ends in “-” and the found rule starts with the search rule.
+            // Either no search pattern was given
+            // or the search pattern matches the found declaration's property name exactly
+            // or the search pattern ends in “-”
+            // ... and the found declaration's property name starts with the search pattern
             if (
                 $searchPattern === null || $propertyName === $searchPattern
                 || (
@@ -208,9 +210,9 @@ public function getRules(?string $searchPattern = null): array
     }
 
     /**
-     * Overrides all the rules of this set.
+     * Overrides all the declarations of this set.
      *
-     * @param array<Declaration> $declarations The rules to override with.
+     * @param array<Declaration> $declarations
      */
     public function setRules(array $declarations): void
     {
@@ -221,16 +223,17 @@ public function setRules(array $declarations): void
     }
 
     /**
-     * Returns all rules matching the given pattern and returns them in an associative array with the rule’s name
-     * as keys. This method exists mainly for backwards-compatibility and is really only partially useful.
+     * Returns all declarations with property names matching the given pattern and returns them in an associative array
+     * with the property names as keys.
+     * This method exists mainly for backwards-compatibility and is really only partially useful.
      *
      * Note: This method loses some information: Calling this (with an argument of `background-`) on a declaration block
      * like `{ background-color: green; background-color; rgba(0, 127, 0, 0.7); }` will only yield an associative array
-     * containing the rgba-valued rule while `getRules()` would yield an indexed array containing both.
+     * containing the rgba-valued declaration while `getDeclarations()` would yield an indexed array containing both.
      *
      * @param string|null $searchPattern
-     *        Pattern to search for. If null, returns all rules. If the pattern ends with a dash,
-     *        all rules starting with the pattern are returned as well as one matching the pattern with the dash
+     *        Pattern to search for. If null, returns all declarations. If the pattern ends with a dash,
+     *        all declarations starting with the pattern are returned as well as one matching the pattern with the dash
      *        excluded.
      *
      * @return array<string, Declaration>
@@ -263,20 +266,20 @@ public function removeRule(Declaration $declarationToRemove): void
     }
 
     /**
-     * Removes rules by property name or search pattern.
+     * Removes declarations by property name or search pattern.
      *
      * @param string $searchPattern
      *        pattern to remove.
      *        If the pattern ends in a dash,
-     *        all rules starting with the pattern are removed as well as one matching the pattern with the dash
+     *        all declarations starting with the pattern are removed as well as one matching the pattern with the dash
      *        excluded.
      */
     public function removeMatchingRules(string $searchPattern): void
     {
         foreach ($this->declarations as $propertyName => $declarations) {
-            // Either the search rule matches the found rule exactly
-            // or the search rule ends in “-” and the found rule starts with the search rule or equals it
-            // (without the trailing dash).
+            // Either the search pattern matches the found declaration's property name exactly
+            // or the search pattern ends in “-” and the found declaration's property name starts with the search
+            // pattern or equals it (without the trailing dash).
             if (
                 $propertyName === $searchPattern
                 || (\strrpos($searchPattern, '-') === \strlen($searchPattern) - \strlen('-')