docs: clarify JSONPath filter expression syntax [skip ci]

Author: jg-rp

CHANGELOG.md

@@ -1,6 +1,6 @@
 # Python JSONPath Change Log
 
-## Version 0.10.2 (unreleased)
+## Version 0.10.2
 
 **Fixes**
 

docs/advanced.md

@@ -4,7 +4,7 @@
 
 Arbitrary variables can be made available to [filter expressions](syntax.md#filters-expression) using the _filter_context_ argument to [`findall()`](quickstart.md#findallpath-data) and [`finditer()`](quickstart.md#finditerpath-data). _filter_context_ should be a [mapping](https://docs.python.org/3/library/typing.html#typing.Mapping) of strings to JSON-like objects, like lists, dictionaries, strings and integers.
 
-Filter context variables are selected using the _filter context selector_, which defaults to `_` and has usage similar to `$` and `@`.
+Filter context variables are selected using a filter query starting with the _filter context identifier_, which defaults to `_` and has usage similar to `$` and `@`.
 
 ```python
 import jsonpath

docs/syntax.md

@@ -122,7 +122,7 @@ $...title
 
 ### Filters (`[?EXPRESSION]`)
 
-Filters allow you to remove nodes from a selection using a Boolean expression. When filtering a mapping-like object, `#` references the current key/property and `@` references the current value associated with `#`. When filtering a sequence-like object, `@` references the current item and `#` will hold the item's index in the sequence.
+Filters allow you to remove nodes from a selection using a Boolean expression. A _filter query_ is a JSONPath query nested within a filter expression. Every filter query must start with the root identifier (`$`), the current node identifier (`@`) or the [filter context](advanced.md#filter-variables) identifier (`_`).
 
 ```text
 $..products[?(@.price < $.price_cap)]
@@ -132,30 +132,36 @@ $..products[?(@.price < $.price_cap)]
 $..products[[email protected] < $.price_cap]
 ```
 
+When filtering a mapping-like object, `#` references the current key/property and `@` references the current value associated with `#`. When filtering a sequence-like object, `@` references the current item and `#` will hold the item's index in the sequence.
+
 Comparison operators include `==`, `!=`, `<`, `>`, `<=` and `>=`. Plus `<>` as an alias for `!=`.
 
 `in` and `contains` are membership operators. `left in right` is equivalent to `right contains left`.
 
-`&&` and `||` are logical operators, `and` and `or` work too.
+`&&` and `||` are logical operators and terms can be grouped with parentheses. `and` and `or` work too.
 
 `=~` matches the left value with a regular expression literal. Regular expressions use a syntax similar to that found in JavaScript, where the pattern to match is surrounded by slashes, optionally followed by flags.
 
 ```text
 $..products[?(@.description =~ /.*trainers/i)]
 ```
 
-Filter expressions can call predefined [function extensions](functions.md) too.
+A filter query on its own - one that is not part of a comparison expression - is an existence test. We also support comparing a filter query to the special `undefined` keyword. These two example are equivalent.
 
 ```text
-$.categories[?count(@.products.*) >= 2]
+$..products[[email protected]_price]
 ```
 
-`undefined` can be used to filter on the absence of a key/property or an undefined value returned from a filter function. `missing` is an alias for `undefined`.
-
 ```text
 $..products[[email protected]_price == undefined]
 ```
 
+Filter expressions can call predefined [function extensions](functions.md) too.
+
+```text
+$.categories[?count(@.products.*) >= 2]
+```
+
 ### Union (`|`) and intersection (`&`)
 
 Union (`|`) and intersection (`&`) are similar to Python's set operations, but we don't dedupe the matches (matches will often contain unhashable objects).