Add type annotations for Document

Also fix some associated type annotations that have turned out to
be incorrect.

Author: oliverklee

src/CSSList/CSSBlockList.php

@@ -7,7 +7,6 @@
 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;
 
@@ -61,7 +60,7 @@ protected function allRuleSets(array &$aResult)
 
     /**
      * @param CSSList|Rule|RuleSet|Value $oElement
-     * @param array<int, Value|CSSString> $aResult
+     * @param array<int, Value> $aResult
      * @param string|null $sSearchString
      * @param bool $bSearchInFunctionArguments
      *
@@ -86,13 +85,13 @@ 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 array<int, Selector> $aResult
      * @param string|null $sSpecificitySearch
      *
      * @return void

src/CSSList/Document.php

@@ -5,18 +5,18 @@
 use Sabberworm\CSS\OutputFormat;
 use Sabberworm\CSS\Parsing\ParserState;
 use Sabberworm\CSS\Parsing\SourceException;
-use Sabberworm\CSS\Value\CSSString;
+use Sabberworm\CSS\Property\Selector;
+use Sabberworm\CSS\RuleSet\DeclarationBlock;
+use Sabberworm\CSS\RuleSet\RuleSet;
 use Sabberworm\CSS\Value\Value;
 
 /**
- * The root CSSList of a parsed file. Contains all top-level css contents, mostly declaration blocks,
+ * The root `CSSList` of a parsed file. Contains all top-level CSS contents, mostly declaration blocks,
  * but also any at-rules encountered.
  */
 class Document extends CSSBlockList
 {
     /**
-     * Document constructor.
-     *
      * @param int $iLineNo
      */
     public function __construct($iLineNo = 0)
@@ -25,8 +25,6 @@ public function __construct($iLineNo = 0)
     }
 
     /**
-     * @param ParserState $oParserState
-     *
      * @return Document
      *
      * @throws SourceException
@@ -39,16 +37,23 @@ public static function parse(ParserState $oParserState)
     }
 
     /**
-     * Gets all DeclarationBlock objects recursively.
+     * Gets all `DeclarationBlock` objects recursively.
+     *
+     * @return array<int, DeclarationBlock>
      */
     public function getAllDeclarationBlocks()
     {
+        /** @var array<int, DeclarationBlock> $aResult */
         $aResult = [];
         $this->allDeclarationBlocks($aResult);
         return $aResult;
     }
 
     /**
+     * Gets all `DeclarationBlock` objects recursively.
+     *
+     * @return array<int, DeclarationBlock>
+     *
      * @deprecated will be removed in version 9.0; use `getAllDeclarationBlocks()` instead
      */
     public function getAllSelectors()
@@ -57,23 +62,28 @@ public function getAllSelectors()
     }
 
     /**
-     * Returns all RuleSet objects found recursively in the tree.
+     * Returns all `RuleSet` objects found recursively in the tree.
+     *
+     * @return array<int, RuleSet>
      */
     public function getAllRuleSets()
     {
+        /** @var array<int, RuleSet> $aResult */
         $aResult = [];
         $this->allRuleSets($aResult);
         return $aResult;
     }
 
     /**
-     * Returns all Value objects found recursively in the tree.
+     * Returns all `Value` objects found recursively in the tree.
      *
-     * @param object|string $mElement
-     *        the CSSList or RuleSet to start the search from (defaults to the whole document).
+     * @param CSSList|RuleSet|string $mElement
+     *        the `CSSList` or `RuleSet` to start the search from (defaults to the whole document).
      *        If a string is given, it is used as rule name filter.
      * @param bool $bSearchInFunctionArguments whether to also return Value objects used as Function arguments.
      *
+     * @return array<int, Value>
+     *
      * @see RuleSet->getRules()
      */
     public function getAllValues($mElement = null, $bSearchInFunctionArguments = false)
@@ -85,32 +95,38 @@ public function getAllValues($mElement = null, $bSearchInFunctionArguments = fal
             $sSearchString = $mElement;
             $mElement = $this;
         }
-        /** @var array<int, Value|CSSString> $aResult */
+        /** @var array<int, Value> $aResult */
         $aResult = [];
         $this->allValues($mElement, $aResult, $sSearchString, $bSearchInFunctionArguments);
         return $aResult;
     }
 
     /**
-     * Returns all Selector objects found recursively in the tree.
-     * Note that this does not yield the full DeclarationBlock that the selector belongs to
+     * Returns all `Selector` objects found recursively in the tree.
+     *
+     * Note that this does not yield the full `DeclarationBlock` that the selector belongs to
      * (and, currently, there is no way to get to that).
      *
-     * @param string $sSpecificitySearch
+     * @param string|null $sSpecificitySearch
      *        An optional filter by specificity.
      *        May contain a comparison operator and a number or just a number (defaults to "==").
      *
-     * @example getSelectorsBySpecificity('>= 100')
+     * @return array<int, Selector>
+     * @example `getSelectorsBySpecificity('>= 100')`
+     *
      */
     public function getSelectorsBySpecificity($sSpecificitySearch = null)
     {
+        /** @var array<int, Selector> $aResult */
         $aResult = [];
         $this->allSelectors($aResult, $sSpecificitySearch);
         return $aResult;
     }
 
     /**
-     * Expands all shorthand properties to their long value
+     * Expands all shorthand properties to their long value.
+     *
+     * @return void
      */
     public function expandShorthands()
     {
@@ -120,7 +136,9 @@ public function expandShorthands()
     }
 
     /**
-     * Create shorthands properties whenever possible
+     * Create shorthands properties whenever possible.
+     *
+     * @return void
      */
     public function createShorthands()
     {
@@ -130,7 +148,7 @@ public function createShorthands()
     }
 
     /**
-     * Override `render()` to make format argument optional
+     * Overrides `render()` to make format argument optional.
      *
      * @param OutputFormat|null $oOutputFormat
      *
@@ -144,6 +162,9 @@ public function render(OutputFormat $oOutputFormat = null)
         return parent::render($oOutputFormat);
     }
 
+    /**
+     * @return bool
+     */
     public function isRootList()
     {
         return true;