From 6c4c27e8c0d098b80f25632d2eb0d9a3cb609fa7 Mon Sep 17 00:00:00 2001
From: Romain Delamare <romain@delama.re>
Date: Tue, 16 Apr 2024 18:47:09 +0200
Subject: [PATCH] kql: add some explanation for top() matcher

---
 QUERY-SPEC.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/QUERY-SPEC.md b/QUERY-SPEC.md
index bd6a802..371b711 100644
--- a/QUERY-SPEC.md
+++ b/QUERY-SPEC.md
@@ -30,6 +30,11 @@ properties, node names, etc). With the exception of `top()` and `()`, they are a
 used inside a `[]` selector. Some matchers are unary, but most of them involve
 binary operators.
 
+The `top()` matcher can only be used as the first matcher of a selector. This means
+that it cannot be the right operand of the `>`, `>>`, `+`, or `++` operators. As `||`
+combines selectors, the `top()` can appear just after it. For instance,
+ `a > b || top() > b` is valid, but `a > top()` is not.
+
 * `top()`: Returns all toplevel children of the current document.
 * `top() > []`: Equivalent to `top()` on its own.
 * `(foo)`: Selects any element whose type annotation is `foo`.