From 9c54eef45a81de4111b4cfcbb2dc6a6519604e27 Mon Sep 17 00:00:00 2001
From: Shati Patel <shati@semmle.com>
Date: Mon, 30 Sep 2019 10:38:10 +0100
Subject: [PATCH] QL HB: Update aggregation section

---
 docs/language/ql-handbook/expressions.rst | 24 +++++++++++++----------
 1 file changed, 14 insertions(+), 10 deletions(-)

diff --git a/docs/language/ql-handbook/expressions.rst b/docs/language/ql-handbook/expressions.rst
index c73c16db704..03e33693b41 100644
--- a/docs/language/ql-handbook/expressions.rst
+++ b/docs/language/ql-handbook/expressions.rst
@@ -303,22 +303,22 @@ Let us apply these steps to the ``sum`` aggregate in the following query:
 .. code-block:: ql
 
    select sum(int i, int j |
-       exists(string char | char = "hello".charAt(i)) and exists(string char | char = "world!".charAt(j)) | i)
+       exists(string s | s = "hello".charAt(i)) and exists(string s | s = "world!".charAt(j)) | i)
 
 #. Input variables: ``i``, ``j``.
 
 #. All possible tuples ``(<value of i>, <value of j>)`` satisfying the given condition: 
-   ``(0, 0), (0, 1), (0, 2), (0, 3), (0, 4), (0, 5), (1, 0), (1, 1),...,(4, 5)``.
+   ``(0, 0), (0, 1), (0, 2), (0, 3), (0, 4), (0, 5), (1, 0), (1, 1), ..., (4, 5)``.
 
-   ``30`` tuples are generated in this step.
+   30 tuples are generated in this step.
 
 #. Apply the ``<expression> i`` on all tuples. This means selecting all values of ``i`` from 
    all tuples: ``0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2, 3, 3, 3, 3, 3, 3, 4, 4, 4, 4, 4, 4.``
 
 #. Apply the aggregation function ``sum`` on the above values to get the final result ``60``.
 
-If we change ``<expression>`` to ``i+j`` in the above query, the query result is ``135`` since 
-applying ``i+j`` on all tuples results in following values: 
+If we change ``<expression>`` to ``i + j`` in the above query, the query result is ``135`` since 
+applying ``i + j`` on all tuples results in following values: 
 \ ``0, 1, 2, 3, 4, 5, 1, 2, 3, 4, 5, 6, 2, 3, 4, 5, 6, 7, 3, 4, 5, 6, 7, 8, 4, 5, 6, 7, 8, 9``.
 
 Next, consider the following query:
@@ -327,11 +327,15 @@ Next, consider the following query:
  
    select count(string s | s = "hello" | s.charAt(_))
 
-``s`` is the input variable of the aggregate. A single tuple ``("hello")`` is generated after 
-applying step 2. When the ``<expression> charAt(_)`` is applied on this tuple, it generates ``4`` 
-distinct values ``'h', 'e', 'l', 'o'``. Note that ``'l'`` only appears once as this step collects 
-the distinct values generated as a result of applying ``<expression>``. Finally, ``count`` is 
-applied on these values, and the query returns ``4``.  
+#. ``s`` is the input variable of the aggregate.
+
+#. A single tuple ``"hello"`` is generated in this step.
+
+#. The ``<expression> charAt(_)`` is applied on this tuple. The underscore ``_`` in ``charAt(_)``
+   is a :ref:`don't-care expression <dont-care>`, which represents any value.
+   ``s.charAt(_)`` generates four distinct values ``h, e, l, o``.
+
+#. Finally, ``count`` is applied on these values, and the query returns ``4``.