[DomCrawler] Add more details about some methods

javiereguiluz · javiereguiluz · commit f692b0267ad5 · 2025-06-02T09:46:08.000+02:00
diff --git a/testing/dom_crawler.rst b/testing/dom_crawler.rst
@@ -21,27 +21,29 @@ selects the last one on the page, and then selects its immediate ancestor elemen
 Many other methods are also available:
 
 ``filter('h1.title')``
-    Nodes that match the CSS selector.
+    Selects nodes that match the given CSS selector (which must be supported by
+    Symfony's :doc:`CSS Selector component </components/css_selector>`).
 ``filterXpath('h1')``
-    Nodes that match the XPath expression.
+    Selects nodes matching the given `XPath expression`_.
 ``eq(1)``
-    Node for the specified index.
+    Selects the node at the given index (``0`` is the first node)
 ``first()``
-    First node.
+    Selects the first node (equivalent to ``eq(0)``).
 ``last()``
-    Last node.
+    Selects the last node.
 ``siblings()``
-    Siblings.
+    Selects all sibling nodes (nodes with the same parent).
 ``nextAll()``
-    All following siblings.
+    Selects all following siblings (same parent, after the current node).
 ``previousAll()``
-    All preceding siblings.
+    Selects all preceding siblings (same parent, before the current node).
 ``ancestors()``
-    Returns the ancestor nodes.
+    Selects all ancestor nodes (parents, grandparents, etc., up to the ``<html>``
+    element).
 ``children()``
-    Returns children nodes.
+    Selects all direct child nodes of the current node.
 ``reduce($lambda)``
-    Nodes for which the callable does not return false.
+    Filters the nodes using a callback; keeps only those for which it returns ``true``.
 
 Since each of these methods returns a new ``Crawler`` instance, you can
 narrow down your node selection by chaining the method calls::
@@ -91,3 +93,5 @@ The Crawler can extract information from the nodes::
     $data = $crawler->each(function ($node, int $i): string {
         return $node->attr('href');
     });
+
+.. _`XPath expression`: https://developer.mozilla.org/en-US/docs/Web/XML/XPath
