[DomCrawler] Add more details about some methods #21034
Conversation
There was a problem hiding this comment.
Pull Request Overview
This PR enriches the DomCrawler documentation by expanding method descriptions with more detail and adding references to related components and resources.
- Expanded explanations for common Crawler methods to clarify their behavior and usage.
- Added a link to Symfony’s CSS Selector component documentation.
- Introduced an external reference for “XPath expression.”
There was a problem hiding this comment.
We should probably also make it clear which methods are meant to be called on a single-node Crawler because they ignore other nodes than the first one (any method where the implementation rely on using $this->getNode(0) basically).
We have several places guaranteed to be dealing with single-node crawlers in the API:
- the callback of
each - the callback of
reduce - the return value of
eq(and its shortcut) for a valid position (for an invalid position, it will be an empty crawler for which those methods relying on the first node will throw an exception)
| ``first()`` | ||
| First node. | ||
| Selects the first node (equivalent to ``eq(0)``). |
There was a problem hiding this comment.
Using Selects in all those descriptions is confusing to me. We have different kinds of methods in this lists:
- methods creating a Crawler containing only a subset of the nodes of the current Crawler instance (
eqand all its shorcuts, but alsoreducewhich actually filters the current instance andslice) - methods returning a new Crawler with a different selection (which also includes the
filterandfilterXpathmethods, despite their name, as they are doing a mix of matching the existing nodes or finding their descendants)
There was a problem hiding this comment.
You are right, but this doc is in testing/dom_crawler (we also have components/dom_crawler) so this is probably an internal detail not relevant in this page. 🤔
There was a problem hiding this comment.
Well, if you improve the documentation of available methods to make it easier to know what they do (without going to another page), it is relevant to make it clear what they do IMO. Otherwise, you could remove the list and make them go to components/dom_crawler to get the proper explanation.
After merging #21031 I thought that we could improve some explanations of some methods with more details and references.