diff --git a/components/dom_crawler.rst b/components/dom_crawler.rst
index c41d44a185a..864632d4459 100644
--- a/components/dom_crawler.rst
+++ b/components/dom_crawler.rst
@@ -282,6 +282,58 @@ and :phpclass:`DOMNode` objects:
$html = $crawler->html();
+Expression Evaluation
+~~~~~~~~~~~~~~~~~~~~~
+
+The ``evaluate()`` method evaluates the given XPath expression.
+The return value depends on if the expression operates on simple values
+(like HTML attributes), or a subset of the current document.
+If the expression evaluates to a scalar value, an array of results will be
+returned. If the expression evaluates to a DOM document, a new ``Crawler``
+instance will be returned.
+
+This behavior is best illustrated with examples::
+
+ use Symfony\Component\DomCrawler\Crawler;
+
+ $html = '
+
+ Article 1
+ Article 2
+ Article 3
+
+ ';
+
+ $crawler = new Crawler();
+ $crawler->addHtmlContent($html);
+
+ $crawler->filterXPath('//span[contains(@id, "article-")]')->evaluate('substring-after(@id, "-")');
+ // array:3 [
+ // 0 => "100"
+ // 1 => "101"
+ // 2 => "102"
+ // ]
+
+ $crawler->evaluate('substring-after(//span[contains(@id, "article-")]/@id, "-")');
+ // array:1 [
+ // 0 => "100"
+ // ]
+
+ $crawler->filterXPath('//span[@class="article"]')->evaluate('count(@id)');
+ // array:3 [
+ // 0 => 1.0
+ // 1 => 1.0
+ // 2 => 1.0
+ // ]
+
+ $crawler->evaluate('count(//span[@class="article"])');
+ // array:1 [
+ // 0 => 3.0
+ // ]
+
+ $crawler->evaluate('//span[1]');
+ // Symfony\Component\DomCrawler\Crawler { }
+
Links
~~~~~