yeast: Add documentation for query choices

Author: tausbn

shared/yeast-macros/src/lib.rs

@@ -26,6 +26,7 @@ mod template_parse;
 /// (kind)* @capture             - capture each repeated named-node match
 /// "literal"* @capture          - capture each repeated unnamed-token match
 /// (kind)?                      - zero or one named node
+/// [(pattern) (pattern)]        - query choice: try alternatives in order
 /// ```
 ///
 /// Named fields and bare child patterns may be intermixed in any order.
@@ -161,6 +162,9 @@ pub fn trees(input: TokenStream) -> TokenStream {
 /// - `@name` (no quantifier) → `name: OutputId`
 /// - `@name` (after `*`/`+`) → `name: Vec<OutputId>`
 /// - `@name` (after `?`) → `name: Option<OutputId>`
+/// - captures in a query choice are unified by name: a capture in every branch
+///   remains required, a missing/optional capture becomes optional, and any
+///   repeated occurrence makes the binding a vector
 ///
 /// Raw `@@name` captures use the corresponding input `Id` types instead.
 ///

shared/yeast/doc/yeast.md

@@ -178,6 +178,36 @@ Single-pattern and empty query groups are rejected as redundant or meaningless.
 This does not affect the empty output template `()`, which intentionally means
 “emit no replacement nodes.”
 
+### Query choices
+
+A query choice tries its alternatives from left to right and merges captures
+from the selected alternative:
+
+```rust
+[
+    (integer) @number
+    (identifier) @@name
+]
+```
+
+An alternative may contain any query pattern. Parenthesize a sequence of
+sibling patterns to use it as one alternative:
+
+```rust
+[
+    (
+        (item)* @items
+        (separator) @separator
+    )
+    (single_item) @item
+]
+```
+
+Capture bindings are unified by name. A capture present in every alternative
+remains required; one missing or optional in any alternative becomes optional;
+and any repeated occurrence makes the combined binding a vector. The same name
+must consistently use `@` or `@@`.
+
 ## Template language
 
 Templates construct new AST nodes using the `tree!` and `trees!` macros.