Add inline documentation comparing fold expression vs binary tree approaches

Detailed comments explain:
- Why fold expressions achieve O(1) template depth for sequence_merge
- Comprehensive comparison of three approaches: recursive O(N), binary tree O(log N), fold expression O(1)
- Trade-offs: C++17 requirement, ADL complexity, debugging difficulty
- Clear recommendations for when to use each approach
- How operator| enables fold expression pattern via ADL

This documentation helps maintainers understand the performance vs complexity
trade-offs between different sequence merging strategies.

Author: tenpercent

include/ck/utility/sequence.hpp

@@ -199,9 +199,52 @@ template <index_t N>
 using make_index_sequence =
     typename __make_integer_seq<impl::__integer_sequence, index_t, N>::seq_type;
 
-// merge sequence - O(1) template depth using fold expression
-// Binary merge operator for fold expression - enables O(1) depth via (S1 | S2 | S3 | ...)
-// Must be in ck namespace for ADL to find it when used with Sequence types
+// Sequence merge using fold expressions - O(1) template instantiation depth
+//
+// Strategy: Use C++17 fold expressions with custom operator| to achieve true O(1) depth
+//
+// Why fold expressions achieve O(1) depth:
+// - Fold expression: (Seq1{} | Seq2{} | Seq3{} | ...) expands in a single step
+// - Compiler generates flat operation: operator|(operator|(Seq1, Seq2), Seq3), ...
+// - Single instantiation of operator| handles all pairs → O(1) template nesting depth
+//
+// Comparison with alternative approaches:
+//
+// 1. Recursive template (old approach):
+//    - Depth: O(N) - each merge level requires template instantiation
+//    - Example: merge<A,B,C,D> → merge<merge<A,B>, merge<C,D>> → multiple levels
+//
+// 2. Binary tree reduction (alternative O(log N) approach):
+//    - Depth: O(log N) - divides work in half each level
+//    - Example: merge<A,B,C,D> → merge<AB, CD> → ABCD (2 levels for 4 sequences)
+//    - Specializes small cases (1-4 sequences) for common scenarios
+//
+// 3. Fold expression (THIS approach):
+//    - Depth: O(1) - single fold operation regardless of N
+//    - Example: (A | B | C | D) → ABCD (1 level for any N)
+//    - Requires C++17 and understanding of ADL for operator|
+//
+// Impact:
+// - Significantly reduces sequence_merge instantiation count vs recursive approach
+// - Maximum template nesting depth remains constant regardless of number of sequences
+// - Compilation time improvement proportional to instantiation reduction
+//
+// Trade-offs:
+// - Requires C++17 fold expressions
+// - Operator| must be found via ADL (Argument-Dependent Lookup) in ck namespace
+// - More abstract than explicit specializations (harder to debug)
+// - Uniform cost for all cases (no special-casing of common small N)
+//
+// Recommendation: Use fold expressions when:
+// - C++17 is available
+// - Maximum compilation performance is critical
+// - Code abstraction is acceptable
+//
+// Use binary tree (alternative approach) when:
+// - Need C++14 compatibility
+// - Want explicit control over small-case optimizations
+// - Debugging and code clarity are prioritized
+//
 template <index_t... As, index_t... Bs>
 constexpr Sequence<As..., Bs...> operator|(Sequence<As...>, Sequence<Bs...>)
 {