[CLEANUP] Make Commentable type annotations more specific (#1171)

oliverklee · web-flow · commit dc3b9cb3d9f3 · 2025-03-16T20:34:06.000Z
diff --git a/config/phpstan-baseline.neon b/config/phpstan-baseline.neon
@@ -108,18 +108,6 @@ parameters:
 			count: 2
 			path: ../src/RuleSet/RuleSet.php
 
-		-
-			message: '#^Parameter \#1 \$comments \(array\<string, Sabberworm\\CSS\\Comment\\Comment\>\) of method Sabberworm\\CSS\\RuleSet\\RuleSet\:\:addComments\(\) should be contravariant with parameter \$comments \(array\<Sabberworm\\CSS\\Comment\\Comment\>\) of method Sabberworm\\CSS\\Comment\\Commentable\:\:addComments\(\)$#'
-			identifier: method.childParameterType
-			count: 1
-			path: ../src/RuleSet/RuleSet.php
-
-		-
-			message: '#^Parameter \#1 \$comments \(array\<string, Sabberworm\\CSS\\Comment\\Comment\>\) of method Sabberworm\\CSS\\RuleSet\\RuleSet\:\:setComments\(\) should be contravariant with parameter \$comments \(array\<Sabberworm\\CSS\\Comment\\Comment\>\) of method Sabberworm\\CSS\\Comment\\Commentable\:\:setComments\(\)$#'
-			identifier: method.childParameterType
-			count: 1
-			path: ../src/RuleSet/RuleSet.php
-
 		-
 			message: '#^Parameters should have "Sabberworm\\CSS\\Rule\\Rule" types as the only types passed to this method$#'
 			identifier: typePerfect.narrowPublicClassMethodParamType
diff --git a/src/CSSList/CSSList.php b/src/CSSList/CSSList.php
@@ -34,7 +34,7 @@
 abstract class CSSList implements Renderable, Commentable
 {
     /**
-     * @var array<array-key, Comment>
+     * @var list<Comment>
      *
      * @internal since 8.8.0
      */
@@ -460,23 +460,23 @@ public function getContents()
     }
 
     /**
-     * @param array<array-key, Comment> $comments
+     * @param list<Comment> $comments
      */
     public function addComments(array $comments): void
     {
         $this->comments = \array_merge($this->comments, $comments);
     }
 
     /**
-     * @return array<array-key, Comment>
+     * @return list<Comment>
      */
     public function getComments(): array
     {
         return $this->comments;
     }
 
     /**
-     * @param array<array-key, Comment> $comments
+     * @param list<Comment> $comments
      */
     public function setComments(array $comments): void
     {
diff --git a/src/Comment/Commentable.php b/src/Comment/Commentable.php
@@ -7,17 +7,17 @@
 interface Commentable
 {
     /**
-     * @param array<array-key, Comment> $comments
+     * @param list<Comment> $comments
      */
     public function addComments(array $comments): void;
 
     /**
-     * @return array<array-key, Comment>
+     * @return list<Comment>
      */
     public function getComments(): array;
 
     /**
-     * @param array<array-key, Comment> $comments
+     * @param list<Comment> $comments
      */
     public function setComments(array $comments): void;
 }
diff --git a/src/Property/CSSNamespace.php b/src/Property/CSSNamespace.php
@@ -28,7 +28,7 @@ class CSSNamespace implements AtRule
     private $lineNumber;
 
     /**
-     * @var array<array-key, Comment>
+     * @var list<Comment>
      *
      * @internal since 8.8.0
      */
@@ -121,23 +121,23 @@ public function atRuleArgs(): array
     }
 
     /**
-     * @param array<array-key, Comment> $comments
+     * @param list<Comment> $comments
      */
     public function addComments(array $comments): void
     {
         $this->comments = \array_merge($this->comments, $comments);
     }
 
     /**
-     * @return array<array-key, Comment>
+     * @return list<Comment>
      */
     public function getComments(): array
     {
         return $this->comments;
     }
 
     /**
-     * @param array<array-key, Comment> $comments
+     * @param list<Comment> $comments
      */
     public function setComments(array $comments): void
     {
diff --git a/src/Property/Charset.php b/src/Property/Charset.php
@@ -31,7 +31,7 @@ class Charset implements AtRule
     protected $lineNumber;
 
     /**
-     * @var array<array-key, Comment>
+     * @var list<Comment>
      *
      * @internal since 8.8.0
      */
@@ -101,23 +101,23 @@ public function atRuleArgs()
     }
 
     /**
-     * @param array<array-key, Comment> $comments
+     * @param list<Comment> $comments
      */
     public function addComments(array $comments): void
     {
         $this->comments = \array_merge($this->comments, $comments);
     }
 
     /**
-     * @return array<array-key, Comment>
+     * @return list<Comment>
      */
     public function getComments(): array
     {
         return $this->comments;
     }
 
     /**
-     * @param array<array-key, Comment> $comments
+     * @param list<Comment> $comments
      */
     public function setComments(array $comments): void
     {
diff --git a/src/Property/Import.php b/src/Property/Import.php
@@ -31,7 +31,7 @@ class Import implements AtRule
     protected $lineNumber;
 
     /**
-     * @var array<array-key, Comment>
+     * @var list<Comment>
      *
      * @internal since 8.8.0
      */
@@ -101,23 +101,23 @@ public function atRuleArgs(): array
     }
 
     /**
-     * @param array<array-key, Comment> $comments
+     * @param list<Comment> $comments
      */
     public function addComments(array $comments): void
     {
         $this->comments = \array_merge($this->comments, $comments);
     }
 
     /**
-     * @return array<array-key, Comment>
+     * @return list<Comment>
      */
     public function getComments(): array
     {
         return $this->comments;
     }
 
     /**
-     * @param array<array-key, Comment> $comments
+     * @param list<Comment> $comments
      */
     public function setComments(array $comments): void
     {
diff --git a/src/Rule/Rule.php b/src/Rule/Rule.php
@@ -49,7 +49,7 @@ class Rule implements Renderable, Commentable
     protected $columnNumber;
 
     /**
-     * @var array<array-key, Comment>
+     * @var list<Comment>
      *
      * @internal since 8.8.0
      */
@@ -249,23 +249,23 @@ public function render(OutputFormat $outputFormat): string
     }
 
     /**
-     * @param array<array-key, Comment> $comments
+     * @param list<Comment> $comments
      */
     public function addComments(array $comments): void
     {
         $this->comments = \array_merge($this->comments, $comments);
     }
 
     /**
-     * @return array<array-key, Comment>
+     * @return list<Comment>
      */
     public function getComments(): array
     {
         return $this->comments;
     }
 
     /**
-     * @param array<array-key, Comment> $comments
+     * @param list<Comment> $comments
      */
     public function setComments(array $comments): void
     {
diff --git a/src/RuleSet/RuleSet.php b/src/RuleSet/RuleSet.php
@@ -40,7 +40,7 @@ abstract class RuleSet implements Renderable, Commentable
     protected $lineNumber;
 
     /**
-     * @var array<array-key, Comment>
+     * @var list<Comment>
      *
      * @internal since 8.8.0
      */
@@ -305,23 +305,23 @@ protected function renderRules(OutputFormat $outputFormat): string
     }
 
     /**
-     * @param array<string, Comment> $comments
+     * @param list<Comment> $comments
      */
     public function addComments(array $comments): void
     {
         $this->comments = \array_merge($this->comments, $comments);
     }
 
     /**
-     * @return array<string, Comment>
+     * @return list<Comment>
      */
     public function getComments(): array
     {
         return $this->comments;
     }
 
     /**
-     * @param array<string, Comment> $comments
+     * @param list<Comment> $comments
      */
     public function setComments(array $comments): void
     {

Original file line number	Diff line number	Diff line change
`@@ -34,7 +34,7 @@`
`34`	`34`	`abstract class CSSList implements Renderable, Commentable`
`35`	`35`	`{`
`36`	`36`	`/**`
`37`		`- * @var array<array-key, Comment>`
	`37`	`+ * @var list<Comment>`
`38`	`38`	`*`
`39`	`39`	`* @internal since 8.8.0`
`40`	`40`	`*/`
`@@ -460,23 +460,23 @@ public function getContents()`
`460`	`460`	`}`
`461`	`461`
`462`	`462`	`/**`
`463`		`- * @param array<array-key, Comment> $comments`
	`463`	`+ * @param list<Comment> $comments`
`464`	`464`	`*/`
`465`	`465`	`public function addComments(array $comments): void`
`466`	`466`	`{`
`467`	`467`	`$this->comments = \array_merge($this->comments, $comments);`
`468`	`468`	`}`
`469`	`469`
`470`	`470`	`/**`
`471`		`- * @return array<array-key, Comment>`
	`471`	`+ * @return list<Comment>`
`472`	`472`	`*/`
`473`	`473`	`public function getComments(): array`
`474`	`474`	`{`
`475`	`475`	`return $this->comments;`
`476`	`476`	`}`
`477`	`477`
`478`	`478`	`/**`
`479`		`- * @param array<array-key, Comment> $comments`
	`479`	`+ * @param list<Comment> $comments`
`480`	`480`	`*/`
`481`	`481`	`public function setComments(array $comments): void`
`482`	`482`	`{`
Original file line number	Diff line number	Diff line change
`@@ -28,7 +28,7 @@ class CSSNamespace implements AtRule`
`28`	`28`	`private $lineNumber;`
`29`	`29`
`30`	`30`	`/**`
`31`		`- * @var array<array-key, Comment>`
	`31`	`+ * @var list<Comment>`
`32`	`32`	`*`
`33`	`33`	`* @internal since 8.8.0`
`34`	`34`	`*/`
`@@ -121,23 +121,23 @@ public function atRuleArgs(): array`
`121`	`121`	`}`
`122`	`122`
`123`	`123`	`/**`
`124`		`- * @param array<array-key, Comment> $comments`
	`124`	`+ * @param list<Comment> $comments`
`125`	`125`	`*/`
`126`	`126`	`public function addComments(array $comments): void`
`127`	`127`	`{`
`128`	`128`	`$this->comments = \array_merge($this->comments, $comments);`
`129`	`129`	`}`
`130`	`130`
`131`	`131`	`/**`
`132`		`- * @return array<array-key, Comment>`
	`132`	`+ * @return list<Comment>`
`133`	`133`	`*/`
`134`	`134`	`public function getComments(): array`
`135`	`135`	`{`
`136`	`136`	`return $this->comments;`
`137`	`137`	`}`
`138`	`138`
`139`	`139`	`/**`
`140`		`- * @param array<array-key, Comment> $comments`
	`140`	`+ * @param list<Comment> $comments`
`141`	`141`	`*/`
`142`	`142`	`public function setComments(array $comments): void`
`143`	`143`	`{`
Original file line number	Diff line number	Diff line change
`@@ -31,7 +31,7 @@ class Charset implements AtRule`
`31`	`31`	`protected $lineNumber;`
`32`	`32`
`33`	`33`	`/**`
`34`		`- * @var array<array-key, Comment>`
	`34`	`+ * @var list<Comment>`
`35`	`35`	`*`
`36`	`36`	`* @internal since 8.8.0`
`37`	`37`	`*/`
`@@ -101,23 +101,23 @@ public function atRuleArgs()`
`101`	`101`	`}`
`102`	`102`
`103`	`103`	`/**`
`104`		`- * @param array<array-key, Comment> $comments`
	`104`	`+ * @param list<Comment> $comments`
`105`	`105`	`*/`
`106`	`106`	`public function addComments(array $comments): void`
`107`	`107`	`{`
`108`	`108`	`$this->comments = \array_merge($this->comments, $comments);`
`109`	`109`	`}`
`110`	`110`
`111`	`111`	`/**`
`112`		`- * @return array<array-key, Comment>`
	`112`	`+ * @return list<Comment>`
`113`	`113`	`*/`
`114`	`114`	`public function getComments(): array`
`115`	`115`	`{`
`116`	`116`	`return $this->comments;`
`117`	`117`	`}`
`118`	`118`
`119`	`119`	`/**`
`120`		`- * @param array<array-key, Comment> $comments`
	`120`	`+ * @param list<Comment> $comments`
`121`	`121`	`*/`
`122`	`122`	`public function setComments(array $comments): void`
`123`	`123`	`{`
Original file line number	Diff line number	Diff line change
`@@ -31,7 +31,7 @@ class Import implements AtRule`
`31`	`31`	`protected $lineNumber;`
`32`	`32`
`33`	`33`	`/**`
`34`		`- * @var array<array-key, Comment>`
	`34`	`+ * @var list<Comment>`
`35`	`35`	`*`
`36`	`36`	`* @internal since 8.8.0`
`37`	`37`	`*/`
`@@ -101,23 +101,23 @@ public function atRuleArgs(): array`
`101`	`101`	`}`
`102`	`102`
`103`	`103`	`/**`
`104`		`- * @param array<array-key, Comment> $comments`
	`104`	`+ * @param list<Comment> $comments`
`105`	`105`	`*/`
`106`	`106`	`public function addComments(array $comments): void`
`107`	`107`	`{`
`108`	`108`	`$this->comments = \array_merge($this->comments, $comments);`
`109`	`109`	`}`
`110`	`110`
`111`	`111`	`/**`
`112`		`- * @return array<array-key, Comment>`
	`112`	`+ * @return list<Comment>`
`113`	`113`	`*/`
`114`	`114`	`public function getComments(): array`
`115`	`115`	`{`
`116`	`116`	`return $this->comments;`
`117`	`117`	`}`
`118`	`118`
`119`	`119`	`/**`
`120`		`- * @param array<array-key, Comment> $comments`
	`120`	`+ * @param list<Comment> $comments`
`121`	`121`	`*/`
`122`	`122`	`public function setComments(array $comments): void`
`123`	`123`	`{`
Original file line number	Diff line number	Diff line change
`@@ -49,7 +49,7 @@ class Rule implements Renderable, Commentable`
`49`	`49`	`protected $columnNumber;`
`50`	`50`
`51`	`51`	`/**`
`52`		`- * @var array<array-key, Comment>`
	`52`	`+ * @var list<Comment>`
`53`	`53`	`*`
`54`	`54`	`* @internal since 8.8.0`
`55`	`55`	`*/`
`@@ -249,23 +249,23 @@ public function render(OutputFormat $outputFormat): string`
`249`	`249`	`}`
`250`	`250`
`251`	`251`	`/**`
`252`		`- * @param array<array-key, Comment> $comments`
	`252`	`+ * @param list<Comment> $comments`
`253`	`253`	`*/`
`254`	`254`	`public function addComments(array $comments): void`
`255`	`255`	`{`
`256`	`256`	`$this->comments = \array_merge($this->comments, $comments);`
`257`	`257`	`}`
`258`	`258`
`259`	`259`	`/**`
`260`		`- * @return array<array-key, Comment>`
	`260`	`+ * @return list<Comment>`
`261`	`261`	`*/`
`262`	`262`	`public function getComments(): array`
`263`	`263`	`{`
`264`	`264`	`return $this->comments;`
`265`	`265`	`}`
`266`	`266`
`267`	`267`	`/**`
`268`		`- * @param array<array-key, Comment> $comments`
	`268`	`+ * @param list<Comment> $comments`
`269`	`269`	`*/`
`270`	`270`	`public function setComments(array $comments): void`
`271`	`271`	`{`
Original file line number	Diff line number	Diff line change
`@@ -40,7 +40,7 @@ abstract class RuleSet implements Renderable, Commentable`
`40`	`40`	`protected $lineNumber;`
`41`	`41`
`42`	`42`	`/**`
`43`		`- * @var array<array-key, Comment>`
	`43`	`+ * @var list<Comment>`
`44`	`44`	`*`
`45`	`45`	`* @internal since 8.8.0`
`46`	`46`	`*/`
`@@ -305,23 +305,23 @@ protected function renderRules(OutputFormat $outputFormat): string`
`305`	`305`	`}`
`306`	`306`
`307`	`307`	`/**`
`308`		`- * @param array<string, Comment> $comments`
	`308`	`+ * @param list<Comment> $comments`
`309`	`309`	`*/`
`310`	`310`	`public function addComments(array $comments): void`
`311`	`311`	`{`
`312`	`312`	`$this->comments = \array_merge($this->comments, $comments);`
`313`	`313`	`}`
`314`	`314`
`315`	`315`	`/**`
`316`		`- * @return array<string, Comment>`
	`316`	`+ * @return list<Comment>`
`317`	`317`	`*/`
`318`	`318`	`public function getComments(): array`
`319`	`319`	`{`
`320`	`320`	`return $this->comments;`
`321`	`321`	`}`
`322`	`322`
`323`	`323`	`/**`
`324`		`- * @param array<string, Comment> $comments`
	`324`	`+ * @param list<Comment> $comments`
`325`	`325`	`*/`
`326`	`326`	`public function setComments(array $comments): void`
`327`	`327`	`{`