From fd8aacaf7a0373920807d138f092598a18a0a394 Mon Sep 17 00:00:00 2001 From: Oliver Klee Date: Sun, 27 Jun 2021 11:19:02 +0200 Subject: [PATCH] Add type annotations for `CSSList` --- src/CSSList/CSSList.php | 90 ++++++++++++++++++++++++++++++----------- 1 file changed, 67 insertions(+), 23 deletions(-) diff --git a/src/CSSList/CSSList.php b/src/CSSList/CSSList.php index 752339cf..24714834 100644 --- a/src/CSSList/CSSList.php +++ b/src/CSSList/CSSList.php @@ -2,10 +2,12 @@ namespace Sabberworm\CSS\CSSList; +use Sabberworm\CSS\Comment\Comment; use Sabberworm\CSS\Comment\Commentable; use Sabberworm\CSS\OutputFormat; use Sabberworm\CSS\Parsing\ParserState; use Sabberworm\CSS\Parsing\SourceException; +use Sabberworm\CSS\Parsing\UnexpectedEOFException; use Sabberworm\CSS\Parsing\UnexpectedTokenException; use Sabberworm\CSS\Property\AtRule; use Sabberworm\CSS\Property\Charset; @@ -22,18 +24,20 @@ use Sabberworm\CSS\Value\Value; /** - * A CSSList is the most generic container available. Its contents include RuleSet as well as other CSSList objects. - * Also, it may contain Import and Charset objects stemming from at-rules. + * A `CSSList` is the most generic container available. Its contents include `RuleSet` as well as other `CSSList` + * objects. + * + * Also, it may contain `Import` and `Charset` objects stemming from at-rules. */ abstract class CSSList implements Renderable, Commentable { /** - * @var array + * @var array $aComments */ protected $aComments; /** - * @var array + * @var array */ protected $aContents; @@ -52,6 +56,12 @@ public function __construct($iLineNo = 0) $this->iLineNo = $iLineNo; } + /** + * @throws SourceException + * @throws UnexpectedTokenException + * + * @return void + */ public static function parseList(ParserState $oParserState, CSSList $oList) { $bIsRoot = $oList instanceof Document; @@ -86,6 +96,13 @@ public static function parseList(ParserState $oParserState, CSSList $oList) } } + /** + * @return AtRuleBlockList|KeyFrame|Charset|CSSNamespace|Import|AtRuleSet|DeclarationBlock|null|false + * + * @throws SourceException + * @throws UnexpectedEOFException + * @throws UnexpectedTokenException + */ private static function parseListItem(ParserState $oParserState, CSSList $oList) { $bIsRoot = $oList instanceof Document; @@ -130,6 +147,15 @@ private static function parseListItem(ParserState $oParserState, CSSList $oList) } } + /** + * @param ParserState $oParserState + * + * @return AtRuleBlockList|KeyFrame|Charset|CSSNamespace|Import|AtRuleSet|null + * + * @throws SourceException + * @throws UnexpectedTokenException + * @throws UnexpectedEOFException + */ private static function parseAtRule(ParserState $oParserState) { $oParserState->consume('@'); @@ -213,6 +239,11 @@ private static function parseAtRule(ParserState $oParserState) /** * Tests an identifier for a given value. Since identifiers are all keywords, they can be vendor-prefixed. * We need to check for these versions too. + * + * @param string $sIdentifier + * @param string $sMatch + * + * @return bool */ private static function identifierIs($sIdentifier, $sMatch) { @@ -229,9 +260,11 @@ public function getLineNo() } /** - * Prepend item to list of contents. + * Prepends an item to the list of contents. + * + * @param RuleSet|CSSList|Import|Charset $oItem * - * @param RuleSet|Import|Charset|CSSList $oItem Item. + * @return void */ public function prepend($oItem) { @@ -239,9 +272,11 @@ public function prepend($oItem) } /** - * Append item to list of contents. + * Appends an item to tje list of contents. + * + * @param RuleSet|CSSList|Import|Charset $oItem * - * @param RuleSet|Import|Charset|CSSList $oItem Item. + * @return void */ public function append($oItem) { @@ -249,11 +284,13 @@ public function append($oItem) } /** - * Splice the list of contents. + * Splices the list of contents. * - * @param int $iOffset Offset. - * @param int $iLength Length. Optional. - * @param RuleSet[] $mReplacement Replacement. Optional. + * @param int $iOffset + * @param int $iLength + * @param array $mReplacement + * + * @return void */ public function splice($iOffset, $iLength = null, $mReplacement = null) { @@ -267,7 +304,7 @@ public function splice($iOffset, $iLength = null, $mReplacement = null) * May be a RuleSet (most likely a DeclarationBlock), a Import, * a Charset or another CSSList (most likely a MediaQuery) * - * @return bool Whether the item was removed. + * @return bool whether the item was removed */ public function remove($oItemToRemove) { @@ -283,8 +320,10 @@ public function remove($oItemToRemove) * Replaces an item from the CSS list. * * @param RuleSet|Import|Charset|CSSList $oOldItem - * May be a RuleSet (most likely a DeclarationBlock), a Import, a Charset - * or another CSSList (most likely a MediaQuery) + * May be a `RuleSet` (most likely a `DeclarationBlock`), an `Import`, a `Charset` + * or another `CSSList` (most likely a `MediaQuery`) + * + * @return bool */ public function replace($oOldItem, $mNewItem) { @@ -301,9 +340,7 @@ public function replace($oOldItem, $mNewItem) } /** - * Set the contents. - * - * @param array $aContents Objects to set as content. + * @param array $aContents */ public function setContents(array $aContents) { @@ -316,8 +353,10 @@ public function setContents(array $aContents) /** * Removes a declaration block from the CSS list if it matches all given selectors. * - * @param array|string $mSelector The selectors to match. - * @param boolean $bRemoveAll Whether to stop at the first declaration block found or remove all blocks + * @param DeclarationBlock|array|string $mSelector the selectors to match + * @param bool $bRemoveAll whether to stop at the first declaration block found or remove all blocks + * + * @return void */ public function removeDeclarationBlockBySelector($mSelector, $bRemoveAll = false) { @@ -352,6 +391,9 @@ public function removeDeclarationBlockBySelector($mSelector, $bRemoveAll = false } } + /** + * @return string + */ public function __toString() { return $this->render(new OutputFormat()); @@ -394,6 +436,8 @@ public function render(OutputFormat $oOutputFormat) /** * Return true if the list can not be further outdented. Only important when rendering. + * + * @return bool */ abstract public function isRootList(); @@ -406,7 +450,7 @@ public function getContents() } /** - * @param array $aComments Array of comments. + * @param array $aComments */ public function addComments(array $aComments) { @@ -414,7 +458,7 @@ public function addComments(array $aComments) } /** - * @return array + * @return array */ public function getComments() { @@ -422,7 +466,7 @@ public function getComments() } /** - * @param array $aComments Array containing Comment objects. + * @param array $aComments */ public function setComments(array $aComments) {