From 22081d2cfd52e56ffc65cc4ff0cdc39203f512e1 Mon Sep 17 00:00:00 2001
From: Oliver Klee <github@oliverklee.de>
Date: Fri, 2 Jul 2021 14:07:13 +0200
Subject: [PATCH] Add type annotations for `CSSBlockList`

---
 src/CSSList/CSSBlockList.php | 39 +++++++++++++++++++++++++++++++++---
 src/CSSList/Document.php     |  3 +++
 2 files changed, 39 insertions(+), 3 deletions(-)

diff --git a/src/CSSList/CSSBlockList.php b/src/CSSList/CSSBlockList.php
index e43f2f06..4909d9d5 100644
--- a/src/CSSList/CSSBlockList.php
+++ b/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) {
diff --git a/src/CSSList/Document.php b/src/CSSList/Document.php
index 8bf15b9e..a7410bea 100644
--- a/src/CSSList/Document.php
+++ b/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;