minor symfony#61482 [DomCrawler] Improve phpdoc annotations (nicolas-grekas)

This PR was merged into the 7.4 branch.

Discussion
----------

[DomCrawler] Improve phpdoc annotations

| Q             | A
| ------------- | ---
| Branch?       | 7.4
| Bug fix?      | no
| New feature?  | no
| Deprecations? | no
| Issues        | -
| License       | MIT

Subset of symfony#61356

Commits
-------

c06142a [DomCrawler] Improve phpdoc annotations

Author: nicolas-grekas

.github/expected-missing-return-types.diff

@@ -187,6 +187,23 @@ diff --git a/src/Symfony/Component/DependencyInjection/Extension/PrependExtensio
 -    public function prepend(ContainerBuilder $container);
 +    public function prepend(ContainerBuilder $container): void;
  }
+diff --git a/src/Symfony/Component/DomCrawler/Crawler.php b/src/Symfony/Component/DomCrawler/Crawler.php
+--- a/src/Symfony/Component/DomCrawler/Crawler.php
++++ b/src/Symfony/Component/DomCrawler/Crawler.php
+@@ -405,5 +405,5 @@ class Crawler implements \Countable, \IteratorAggregate
+      * @throws \InvalidArgumentException When current node is empty
+      */
+-    public function closest(string $selector): ?self
++    public function closest(string $selector): ?static
+     {
+         if (!$this->nodes) {
+@@ -646,5 +646,5 @@ class Crawler implements \Countable, \IteratorAggregate
+      * @return array|static
+      */
+-    public function evaluate(string $xpath): array|self
++    public function evaluate(string $xpath): array|static
+     {
+         if (null === $this->document) {
 diff --git a/src/Symfony/Component/Emoji/EmojiTransliterator.php b/src/Symfony/Component/Emoji/EmojiTransliterator.php
 --- a/src/Symfony/Component/Emoji/EmojiTransliterator.php
 +++ b/src/Symfony/Component/Emoji/EmojiTransliterator.php

src/Symfony/Component/DomCrawler/Crawler.php

@@ -37,10 +37,13 @@ class Crawler implements \Countable, \IteratorAggregate
 
     /**
      * A map of cached namespaces.
+     *
+     * @var \ArrayObject<string, string|null>
      */
     private \ArrayObject $cachedNamespaces;
 
     private ?string $baseHref;
+
     private ?\DOMDocument $document = null;
 
     /**
@@ -56,7 +59,7 @@ class Crawler implements \Countable, \IteratorAggregate
     private ?HTML5 $html5Parser = null;
 
     /**
-     * @param \DOMNodeList|\DOMNode|\DOMNode[]|string|null $node A Node to use as the base for the crawling
+     * @param \DOMNodeList<\DOMNode>|\DOMNode|\DOMNode[]|string|null $node A Node to use as the base for the crawling
      */
     public function __construct(
         \DOMNodeList|\DOMNode|array|string|null $node = null,
@@ -107,9 +110,7 @@ public function clear(): void
      * This method uses the appropriate specialized add*() method based
      * on the type of the argument.
      *
-     * @param \DOMNodeList|\DOMNode|\DOMNode[]|string|null $node A node
-     *
-     * @throws \InvalidArgumentException when node is not the expected type
+     * @param \DOMNodeList<\DOMNode>|\DOMNode|\DOMNode[]|string|null $node
      */
     public function add(\DOMNodeList|\DOMNode|array|string|null $node): void
     {
@@ -121,8 +122,6 @@ public function add(\DOMNodeList|\DOMNode|array|string|null $node): void
             $this->addNodes($node);
         } elseif (\is_string($node)) {
             $this->addContent($node);
-        } elseif (null !== $node) {
-            throw new \InvalidArgumentException(\sprintf('Expecting a DOMNodeList or DOMNode instance, an array, a string, or null, but got "%s".', get_debug_type($node)));
         }
     }
 
@@ -232,8 +231,6 @@ public function addXmlContent(string $content, string $charset = 'UTF-8', int $o
 
     /**
      * Adds a \DOMDocument to the list of nodes.
-     *
-     * @param \DOMDocument $dom A \DOMDocument instance
      */
     public function addDocument(\DOMDocument $dom): void
     {
@@ -245,7 +242,7 @@ public function addDocument(\DOMDocument $dom): void
     /**
      * Adds a \DOMNodeList to the list of nodes.
      *
-     * @param \DOMNodeList $nodes A \DOMNodeList instance
+     * @param \DOMNodeList<\DOMNode> $nodes
      */
     public function addNodeList(\DOMNodeList $nodes): void
     {
@@ -259,7 +256,7 @@ public function addNodeList(\DOMNodeList $nodes): void
     /**
      * Adds an array of \DOMNode instances to the list of nodes.
      *
-     * @param \DOMNode[] $nodes An array of \DOMNode instances
+     * @param \DOMNode[] $nodes
      */
     public function addNodes(array $nodes): void
     {
@@ -270,8 +267,6 @@ public function addNodes(array $nodes): void
 
     /**
      * Adds a \DOMNode instance to the list of nodes.
-     *
-     * @param \DOMNode $node A \DOMNode instance
      */
     public function addNode(\DOMNode $node): void
     {
@@ -313,13 +308,13 @@ public function eq(int $position): static
      *
      * Example:
      *
-     *     $crawler->filter('h1')->each(function ($node, $i) {
-     *         return $node->text();
-     *     });
+     *     $crawler->filter('h1')->each(fn ($node, $i) => $node->text());
+     *
+     * @template R of mixed
      *
-     * @param \Closure $closure An anonymous function
+     * @param \Closure(static, int):R $closure
      *
-     * @return array An array of values returned by the anonymous function
+     * @return list<R> An array of values returned by the anonymous function
      */
     public function each(\Closure $closure): array
     {
@@ -344,7 +339,7 @@ public function slice(int $offset = 0, ?int $length = null): static
      *
      * To remove a node from the list, the anonymous function must return false.
      *
-     * @param \Closure $closure An anonymous function
+     * @param \Closure(static, int):bool $closure
      */
     public function reduce(\Closure $closure): static
     {
@@ -377,7 +372,7 @@ public function last(): static
     /**
      * Returns the siblings nodes of the current selection.
      *
-     * @throws \InvalidArgumentException When current node is empty
+     * @throws \InvalidArgumentException When the current node is empty
      */
     public function siblings(): static
     {
@@ -405,6 +400,8 @@ public function matches(string $selector): bool
      *
      * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/closest#Polyfill
      *
+     * @return ?static
+     *
      * @throws \InvalidArgumentException When current node is empty
      */
     public function closest(string $selector): ?self
@@ -444,7 +441,7 @@ public function nextAll(): static
     /**
      * Returns the previous sibling nodes of the current selection.
      *
-     * @throws \InvalidArgumentException
+     * @throws \InvalidArgumentException When current node is empty
      */
     public function previousAll(): static
     {
@@ -481,7 +478,7 @@ public function ancestors(): static
     /**
      * Returns the children nodes of the current selection.
      *
-     * @throws \InvalidArgumentException When current node is empty
+     * @throws \InvalidArgumentException When the current node is empty
      * @throws \RuntimeException         If the CssSelector Component is not available and $selector is provided
      */
     public function children(?string $selector = null): static
@@ -527,7 +524,7 @@ public function attr(string $attribute, ?string $default = null): ?string
     /**
      * Returns the node name of the first node of the list.
      *
-     * @throws \InvalidArgumentException When current node is empty
+     * @throws \InvalidArgumentException When the current node is empty
      */
     public function nodeName(): string
     {
@@ -594,7 +591,7 @@ public function innerText(bool $normalizeWhitespace = true): string
      *
      * @param string|null $default When not null: the value to return when the current node is empty
      *
-     * @throws \InvalidArgumentException When current node is empty
+     * @throws \InvalidArgumentException When the current node is empty
      */
     public function html(?string $default = null): string
     {
@@ -621,6 +618,9 @@ public function html(?string $default = null): string
         return $html;
     }
 
+    /**
+     * @throws \InvalidArgumentException When the current node is empty
+     */
     public function outerHtml(): string
     {
         if (!\count($this)) {
@@ -642,6 +642,8 @@ public function outerHtml(): string
      *
      * Since an XPath expression might evaluate to either a simple type or a \DOMNodeList,
      * this method will return either an array of simple types or a new Crawler instance.
+     *
+     * @return array|static
      */
     public function evaluate(string $xpath): array|self
     {
@@ -1078,7 +1080,7 @@ private function supportsEncoding(string $encoding): bool
     {
         try {
             return '' === @mb_convert_encoding('', $encoding, 'UTF-8');
-        } catch (\Throwable $e) {
+        } catch (\Throwable) {
             return false;
         }
     }
@@ -1178,7 +1180,7 @@ private function discoverNamespace(\DOMXPath $domxpath, string $prefix): ?string
         // ask for one namespace, otherwise we'd get a collection with an item for each node
         $namespaces = $domxpath->query(\sprintf('(//namespace::*[name()="%s"])[last()]', $this->defaultNamespacePrefix === $prefix ? '' : $prefix));
 
-        return $this->cachedNamespaces[$prefix] = ($node = $namespaces->item(0)) ? $node->nodeValue : null;
+        return $this->cachedNamespaces[$prefix] = $namespaces->item(0)?->nodeValue;
     }
 
     private function findNamespacePrefixes(string $xpath): array
@@ -1193,7 +1195,7 @@ private function findNamespacePrefixes(string $xpath): array
     /**
      * Creates a crawler for some subnodes.
      *
-     * @param \DOMNodeList|\DOMNode|\DOMNode[]|string|null $nodes
+     * @param \DOMNodeList<\DOMNode>|\DOMNode|\DOMNode[]|string|null $nodes
      */
     private function createSubCrawler(\DOMNodeList|\DOMNode|array|string|null $nodes): static
     {