Merge pull request #302 from oliverklee/task/types/cssblocklist

Add type annotations for `CSSBlockList`

Author: sabberworm

src/CSSList/CSSBlockList.php

@@ -2,23 +2,36 @@
 
 namespace Sabberworm\CSS\CSSList;
 
+use Sabberworm\CSS\Property\Selector;
 use Sabberworm\CSS\Rule\Rule;
 use Sabberworm\CSS\RuleSet\DeclarationBlock;
 use Sabberworm\CSS\RuleSet\RuleSet;
 use Sabberworm\CSS\Value\CSSFunction;
+use Sabberworm\CSS\Value\CSSString;
+use Sabberworm\CSS\Value\Value;
 use Sabberworm\CSS\Value\ValueList;
 
 /**
- * A CSSBlockList is a CSSList whose DeclarationBlocks are guaranteed to contain valid declaration blocks or at-rules.
- * Most CSSLists conform to this category but some at-rules (such as @keyframes) do not.
+ * A `CSSBlockList` is a `CSSList` whose `DeclarationBlock`s are guaranteed to contain valid declaration blocks or
+ * at-rules.
+ *
+ * Most `CSSList`s conform to this category but some at-rules (such as `@keyframes`) do not.
  */
 abstract class CSSBlockList extends CSSList
 {
+    /**
+     * @param int $iLineNo
+     */
     public function __construct($iLineNo = 0)
     {
         parent::__construct($iLineNo);
     }
 
+    /**
+     * @param array<int, DeclarationBlock> $aResult
+     *
+     * @return void
+     */
     protected function allDeclarationBlocks(array &$aResult)
     {
         foreach ($this->aContents as $mContent) {
@@ -30,6 +43,11 @@ protected function allDeclarationBlocks(array &$aResult)
         }
     }
 
+    /**
+     * @param array<int, RuleSet> $aResult
+     *
+     * @return void
+     */
     protected function allRuleSets(array &$aResult)
     {
         foreach ($this->aContents as $mContent) {
@@ -41,6 +59,14 @@ protected function allRuleSets(array &$aResult)
         }
     }
 
+    /**
+     * @param CSSList|Rule|RuleSet|Value $oElement
+     * @param array<int, Value|CSSString> $aResult
+     * @param string|null $sSearchString
+     * @param bool $bSearchInFunctionArguments
+     *
+     * @return void
+     */
     protected function allValues($oElement, array &$aResult, $sSearchString = null, $bSearchInFunctionArguments = false)
     {
         if ($oElement instanceof CSSBlockList) {
@@ -60,13 +86,20 @@ protected function allValues($oElement, array &$aResult, $sSearchString = null,
                 }
             }
         } else {
-            //Non-List Value or CSSString (CSS identifier)
+            // Non-List Value or CSSString (CSS identifier)
             $aResult[] = $oElement;
         }
     }
 
+    /**
+     * @param array<int, Selector|string> $aResult
+     * @param string|null $sSpecificitySearch
+     *
+     * @return void
+     */
     protected function allSelectors(array &$aResult, $sSpecificitySearch = null)
     {
+        /** @var array<int, DeclarationBlock> $aDeclarationBlocks */
         $aDeclarationBlocks = [];
         $this->allDeclarationBlocks($aDeclarationBlocks);
         foreach ($aDeclarationBlocks as $oBlock) {

src/CSSList/Document.php

@@ -5,6 +5,8 @@
 use Sabberworm\CSS\OutputFormat;
 use Sabberworm\CSS\Parsing\ParserState;
 use Sabberworm\CSS\Parsing\SourceException;
+use Sabberworm\CSS\Value\CSSString;
+use Sabberworm\CSS\Value\Value;
 
 /**
  * The root CSSList of a parsed file. Contains all top-level css contents, mostly declaration blocks,
@@ -83,6 +85,7 @@ public function getAllValues($mElement = null, $bSearchInFunctionArguments = fal
             $sSearchString = $mElement;
             $mElement = $this;
         }
+        /** @var array<int, Value|CSSString> $aResult */
         $aResult = [];
         $this->allValues($mElement, $aResult, $sSearchString, $bSearchInFunctionArguments);
         return $aResult;