format: indent continuations by 4, and two style conventions

.clang-format

@@ -2,7 +2,13 @@
 Language:        Cpp
 # BasedOnStyle:  LLVM
 AccessModifierOffset: -2
-AlignAfterOpenBracket: AlwaysBreak
+AlignAfterOpenBracket: false
+BreakAfterOpenBracketBracedList: true
+BreakBeforeCloseBracketBracedList: true
+BreakAfterOpenBracketFunction: true
+BreakAfterOpenBracketIf: true
+BreakAfterOpenBracketLoop: true
+BreakAfterOpenBracketSwitch: true
 AlignConsecutiveMacros: false
 AlignConsecutiveAssignments: false
 AlignConsecutiveDeclarations: false
@@ -87,6 +93,13 @@ IndentWrappedFunctionNames: false
 JavaScriptQuotes: Leave
 JavaScriptWrapImports: true
 KeepEmptyLinesAtTheStartOfBlocks: true
+Macros:
+  - 'BOOST_OPENMETHOD(ID, PARAMETERS, RETURN_TYPE)=ID PARAMETERS'
+  - 'BOOST_OPENMETHOD_OVERRIDE(ID, PARAMETERS, RETURN_TYPE)=ID PARAMETERS'
+  - 'BOOST_OPENMETHOD_INLINE_OVERRIDE(ID, PARAMETERS, RETURN_TYPE)=ID PARAMETERS'
+  - 'BOOST_OPENMETHOD_DECLARE_OVERRIDER(ID, PARAMETERS, RETURN_TYPE)=ID PARAMETERS'
+  - 'BOOST_OPENMETHOD_DEFINE_OVERRIDER(ID, PARAMETERS, RETURN_TYPE)=ID PARAMETERS'
+  - 'BOOST_OPENMETHOD_TYPE(ID, PARAMETERS, RETURN_TYPE)=ID PARAMETERS'
 MacroBlockBegin: ''
 MacroBlockEnd:   ''
 MaxEmptyLinesToKeep: 1

CLAUDE.md

@@ -204,10 +204,72 @@ tables before first use.
 ## Code Conventions
 
 ### Formatting
-The project uses clang-format with an LLVM-based style:
-- `AlignAfterOpenBracket: AlwaysBreak`
+
+The project uses clang-format with an LLVM-based style, **pinned to clang-format 22**:
+`dev/reformat` calls `clang-format-22` explicitly, because 18 and 19 reject
+`BreakAfterOpenBracketFunction` with `unknown key` and refuse to run at all.
+
+- `AlignAfterOpenBracket: false`, plus `BreakAfterOpenBracket{Function,If,Loop,Switch}` and the
+  braced-list pair `BreakAfterOpenBracketBracedList` / `BreakBeforeCloseBracketBracedList`.
+  Continuations indent by 4; they are *not* aligned under the open paren. The pre-22 spelling was
+  `AlignAfterOpenBracket: AlwaysBreak`, a misnomer - v22 maps that to `true`, which aligns. No
+  `PenaltyBreak*` value and no `BlockIndent` achieves the 4-space indent; both were probed and
+  ruled out.
 - `AllowShortFunctionsOnASingleLine: false`
 - No short blocks, if statements, or loops on single lines
+- `Macros:` teaches clang-format to expand `BOOST_OPENMETHOD`, `BOOST_OPENMETHOD_OVERRIDE` and
+  their kin to `ID PARAMETERS`. Without it the parameter list is parsed as an *expression*, where
+  `&` is a binary operator, and the first parameter comes out as `Cat & a1`. The expansion
+  deliberately omits the return type: with one in it, clang-format breaks after the return type
+  and indents the method name by 8. `BOOST_OPENMETHOD_OVERRIDER` is deliberately **absent** - it
+  appears in expression position (`...)::fn(args)`), where the expansion never applies and only
+  wrecks the wrapping of the sites that do match.
+
+**A blank line precedes a `return`**, unless the `return` opens its block - the whole body of a
+function or lambda, the body of an `if`, a `case`. Where a comment is attached to the `return`,
+the blank line goes above the comment, not between them. clang-format has no option for this, so
+it is maintained by hand; `dev/reformat` will neither add nor remove these lines.
+
+**Indentation lands on a multiple of 4.** clang-format measures a continuation from the column of
+the enclosing bracket's *content*, not from the line's own indent, so a doubly-nested `((` yields
+13/14/17 and no setting moves it - `AlignAfterOpenBracket` and `AlignOperands` were probed in
+every combination. The fix is to remove a nesting level from the source (hoist the predicate into
+its own trait), never to hunt for an option.
+
+Three shapes clang-format cannot be configured into, so do not go looking:
+
+- **A ternary breaks before `?` only when aligning `:` under the `?` would overflow.** It is
+  fit-driven, so "break both operands unless the whole thing fits on one line" is not expressible.
+- **Macro arguments in expression position keep the binary-operator spacing.** A hand fix to
+  `BOOST_OPENMETHOD_OVERRIDER(poke, (std::ostream & os, ...), void)::fn(...)` is undone by the
+  next run; only `// clang-format off` holds.
+- **Files carrying `// clang-format off`** (most of `doc/modules/ROOT/examples/`) are hand-formatted
+  for the rendered docs. Edit those by hand; a reformat will not touch them.
+
+### `using namespace detail` vs `detail::`
+
+A function body that names `detail::` more than once opens with `using namespace detail;` and
+drops the qualification. A blank line follows the opening run of `using` declarations. The
+directive covers the body only - the signature stays qualified:
+
+```cpp
+static void save(detail::tuple<States...>& to) {
+    using namespace detail;
+
+    (..., (get<States>(to) = get<States>(Registry::state().policies)));
+}
+```
+
+A single use does not earn a directive: the `using` line costs a line, so it pays only where it
+unwraps two or more. Measured across the tree, no single-use body qualified.
+
+Two things a mechanical strip gets wrong - both were hit while doing this:
+
+- **A using-*declaration* is not a use.** In `using detail::generic_compiler;` the qualification
+  *is* the declaration; strip it and `using generic_compiler;` does not compile. Under a directive
+  the declaration is redundant anyway, so delete the line instead of requalifying it.
+- **`BOOST_OPENMETHOD_UNLESS_MRDOCS(detail::)` is not a qualification.** It hides one from MrDocs
+  (see *Reference (MrDocs) constraints*) and must be left alone.
 
 ### Disassembly
 Always show disassembly in **Intel syntax**, never AT&T (the toolchain's default

ce/2-method-vptr-final.cpp

@@ -62,7 +62,8 @@ auto main() -> int {
     Cat felix{"Felix"}, sylvester{"Sylvester"};
     std::vector<virtual_ptr<Animal>> animals = {
         virtual_ptr<Dog>::final(hector), virtual_ptr<Cat>::final(felix),
-        virtual_ptr<Cat>::final(sylvester), virtual_ptr<Dog>::final(snoopy)};
+        virtual_ptr<Cat>::final(sylvester), virtual_ptr<Dog>::final(snoopy)
+    };
 
     meet_animals(animals, std::cout);
 }

ce/2-method-vptr.cpp

@@ -63,7 +63,8 @@ auto main() -> int {
     Dog hector{"Hector"}, snoopy{"Snoopy"};
     Cat felix{"Felix"}, sylvester{"Sylvester"};
     std::vector<virtual_ptr<Animal>> animals = {
-        hector, felix, sylvester, snoopy};
+        hector, felix, sylvester, snoopy
+    };
 
     meet_animals(animals, std::cout);
 }

ce/2-method.cpp

@@ -26,19 +26,19 @@ using boost::openmethod::virtual_;
 BOOST_OPENMETHOD(
     meet, (virtual_<Animal&>, virtual_<Animal&>, std::ostream&), void);
 
-BOOST_OPENMETHOD_OVERRIDE(meet, (Cat & a1, Cat& a2, std::ostream& os), void) {
+BOOST_OPENMETHOD_OVERRIDE(meet, (Cat& a1, Cat& a2, std::ostream& os), void) {
     os << a1.name << " ignores " << a2.name << "\n";
 }
 
-BOOST_OPENMETHOD_OVERRIDE(meet, (Dog & a1, Cat& a2, std::ostream& os), void) {
+BOOST_OPENMETHOD_OVERRIDE(meet, (Dog& a1, Cat& a2, std::ostream& os), void) {
     os << a1.name << " chases " << a2.name << "\n";
 }
 
-BOOST_OPENMETHOD_OVERRIDE(meet, (Cat & a1, Dog& a2, std::ostream& os), void) {
+BOOST_OPENMETHOD_OVERRIDE(meet, (Cat& a1, Dog& a2, std::ostream& os), void) {
     os << a1.name << " runs away from " << a2.name << "\n";
 }
 
-BOOST_OPENMETHOD_OVERRIDE(meet, (Dog & a1, Dog& a2, std::ostream& os), void) {
+BOOST_OPENMETHOD_OVERRIDE(meet, (Dog& a1, Dog& a2, std::ostream& os), void) {
     os << a1.name << " wags tail at " << a2.name << "\n";
 }
 

ce/uni-method-vptr-final.cpp

@@ -49,7 +49,8 @@ auto main() -> int {
     Cat felix{"Felix"}, sylvester{"Sylvester"};
     std::vector<virtual_ptr<Animal>> animals = {
         final_virtual_ptr(hector), virtual_ptr<Cat>::final(felix),
-        final_virtual_ptr(sylvester), virtual_ptr<Dog>::final(snoopy)};
+        final_virtual_ptr(sylvester), virtual_ptr<Dog>::final(snoopy)
+    };
 
     poke_animals(animals, std::cout);
 }

ce/uni-method-vptr.cpp

@@ -48,7 +48,8 @@ auto main() -> int {
     Dog hector{"Hector"}, snoopy{"Snoopy"};
     Cat felix{"Felix"}, sylvester{"Sylvester"};
     std::vector<virtual_ptr<Animal>> animals = {
-        hector, felix, sylvester, snoopy};
+        hector, felix, sylvester, snoopy
+    };
 
     poke_animals(animals, std::cout);
 }

ce/uni-method.cpp

@@ -25,11 +25,11 @@ using boost::openmethod::virtual_;
 
 BOOST_OPENMETHOD(poke, (virtual_<Animal&>, std::ostream&), void);
 
-BOOST_OPENMETHOD_OVERRIDE(poke, (Cat & animal, std::ostream& os), void) {
+BOOST_OPENMETHOD_OVERRIDE(poke, (Cat& animal, std::ostream& os), void) {
     os << animal.name << " hisses.\n";
 }
 
-BOOST_OPENMETHOD_OVERRIDE(poke, (Dog & animal, std::ostream& os), void) {
+BOOST_OPENMETHOD_OVERRIDE(poke, (Dog& animal, std::ostream& os), void) {
     os << animal.name << " barks.\n";
 }
 

dev/reformat

@@ -1,8 +1,11 @@
 #!/bin/bash
 
+# Format every C++ source in the repository. Pinned to clang-format 22: the
+# house style needs BreakAfterOpenBracket*, which 18 and 19 reject outright.
+
 cd "$(dirname $0)/.."
 
-srcs=$(find include examples test \
-    -name '*.?pp' | grep -v cmake_fetchcontent | grep -v /CMakeFiles)
+srcs=$(git ls-files --cached --others --exclude-standard \
+    '*.hpp' '*.cpp' '*.ipp')
 
-clang-format -i --verbose $srcs
+clang-format-22 -i --verbose $srcs

doc/modules/ROOT/examples/default_error_handler.cpp

@@ -24,7 +24,7 @@ BOOST_OPENMETHOD_CLASSES(Animal, Cat, Dog);
 BOOST_OPENMETHOD(trick, (std::ostream&, virtual_ptr<Animal>), void);
 
 BOOST_OPENMETHOD_OVERRIDE(
-    trick, (std::ostream & os, virtual_ptr<Dog> /*dog*/), void) {
+    trick, (std::ostream& os, virtual_ptr<Dog> /*dog*/), void) {
     os << "spin\n";
 }
 

doc/modules/ROOT/examples/headers_namespaces/cat.cpp

@@ -12,12 +12,12 @@ namespace felines {
 BOOST_OPENMETHOD_CLASSES(animals::Animal, Cat, Cheetah);
 
 BOOST_OPENMETHOD_OVERRIDE(
-    poke, (std::ostream & os, virtual_ptr<Cat> cat), void) {
+    poke, (std::ostream& os, virtual_ptr<Cat> cat), void) {
     os << cat->name << " hisses";
 }
 
 BOOST_OPENMETHOD_OVERRIDE(
-    poke, (std::ostream & os, virtual_ptr<Cheetah> cat), void) {
+    poke, (std::ostream& os, virtual_ptr<Cheetah> cat), void) {
     BOOST_OPENMETHOD_OVERRIDER(
         poke, (std::ostream & os, virtual_ptr<Cat> dog), void)::fn(os, cat);
     os << " and runs away";

doc/modules/ROOT/examples/headers_namespaces/dog.cpp

@@ -8,7 +8,7 @@ namespace canines {
 BOOST_OPENMETHOD_CLASSES(animals::Animal, Dog);
 
 BOOST_OPENMETHOD_DEFINE_OVERRIDER(
-    poke, (std::ostream & os, boost::openmethod::virtual_ptr<Dog> dog), void) {
+    poke, (std::ostream& os, boost::openmethod::virtual_ptr<Dog> dog), void) {
     os << dog->name << " barks";
 }
 

doc/modules/ROOT/examples/headers_namespaces/dog.hpp

@@ -13,7 +13,7 @@ struct Dog : animals::Animal {
 };
 
 BOOST_OPENMETHOD_DECLARE_OVERRIDER(
-    poke, (std::ostream & os, boost::openmethod::virtual_ptr<Dog> dog), void);
+    poke, (std::ostream& os, boost::openmethod::virtual_ptr<Dog> dog), void);
 
 } // namespace canines
 

doc/modules/ROOT/examples/headers_namespaces/main.cpp

@@ -15,7 +15,7 @@ struct Bulldog : canines::Dog {
 BOOST_OPENMETHOD_CLASSES(canines::Dog, Bulldog);
 
 BOOST_OPENMETHOD_OVERRIDE(
-    poke, (std::ostream & os, virtual_ptr<Bulldog> dog), void) {
+    poke, (std::ostream& os, virtual_ptr<Bulldog> dog), void) {
     canines::BOOST_OPENMETHOD_OVERRIDER(
         poke, (std::ostream & os, virtual_ptr<canines::Dog> dog),
         void)::fn(os, dog);

doc/modules/ROOT/examples/headers_namespaces/main_unrelated_namespaces.cpp

@@ -18,6 +18,6 @@ BOOST_OPENMETHOD(
 using app_specific_behavior::BOOST_OPENMETHOD_GUIDE(meet);
 
 BOOST_OPENMETHOD_OVERRIDE(
-    meet, (std::ostream & os, virtual_ptr<Animal>, virtual_ptr<Animal>), void) {
+    meet, (std::ostream& os, virtual_ptr<Animal>, virtual_ptr<Animal>), void) {
     os << "ignore";
 }

doc/modules/ROOT/examples/headers_namespaces/main_using_directive.cpp

@@ -17,7 +17,7 @@ struct Bulldog : Dog {
 BOOST_OPENMETHOD_CLASSES(Dog, Bulldog);
 
 BOOST_OPENMETHOD_OVERRIDE(
-    poke, (std::ostream & os, virtual_ptr<Bulldog> dog), void) {
+    poke, (std::ostream& os, virtual_ptr<Bulldog> dog), void) {
     next(os, dog);
     os << " and bites back";
 }

doc/modules/ROOT/examples/rolex/5/main.cpp

@@ -20,7 +20,7 @@ struct Salesman : Employee {
 
 // tag::pay[]
 BOOST_OPENMETHOD(
-    pay, (Payroll & payroll, boost::openmethod::virtual_ptr<const Employee>),
+    pay, (Payroll& payroll, boost::openmethod::virtual_ptr<const Employee>),
     double);
 // end::pay[]
 
@@ -52,7 +52,7 @@ class Payroll {
 
 // tag::overriders[]
 BOOST_OPENMETHOD_OVERRIDE(
-    pay, (Payroll & payroll, boost::openmethod::virtual_ptr<const Employee>),
+    pay, (Payroll& payroll, boost::openmethod::virtual_ptr<const Employee>),
     double) {
     double pay = 5000.0;
     payroll.update_balance(-pay);
@@ -61,8 +61,7 @@ BOOST_OPENMETHOD_OVERRIDE(
 }
 
 BOOST_OPENMETHOD_OVERRIDE(
-    pay,
-    (Payroll & payroll, boost::openmethod::virtual_ptr<const Salesman> emp),
+    pay, (Payroll& payroll, boost::openmethod::virtual_ptr<const Salesman> emp),
     double) {
     double base = next(payroll, emp);
     double commission = emp->sales * 0.05;

doc/modules/ROOT/examples/rolex/6/main.cpp

@@ -20,7 +20,7 @@ struct Salesman : Employee {
 
 // tag::pay[]
 BOOST_OPENMETHOD(
-    pay, (Payroll & payroll, boost::openmethod::virtual_ptr<const Employee>),
+    pay, (Payroll& payroll, boost::openmethod::virtual_ptr<const Employee>),
     double);
 // end::pay[]
 
@@ -46,7 +46,7 @@ class Payroll {
 
 // tag::overriders[]
 BOOST_OPENMETHOD_OVERRIDE(
-    pay, (Payroll & payroll, boost::openmethod::virtual_ptr<const Employee>),
+    pay, (Payroll& payroll, boost::openmethod::virtual_ptr<const Employee>),
     double) {
     double pay = 5000.0;
     payroll.update_balance(-pay);
@@ -55,8 +55,7 @@ BOOST_OPENMETHOD_OVERRIDE(
 }
 
 BOOST_OPENMETHOD_OVERRIDE(
-    pay,
-    (Payroll & payroll, boost::openmethod::virtual_ptr<const Salesman> emp),
+    pay, (Payroll& payroll, boost::openmethod::virtual_ptr<const Salesman> emp),
     double) {
     double base = next(payroll, emp);
     double commission = emp->sales * 0.05;

doc/modules/ROOT/examples/throw_error_handler.cpp

@@ -43,7 +43,7 @@ BOOST_OPENMETHOD_CLASSES(Animal, Cat, Dog);
 BOOST_OPENMETHOD(trick, (std::ostream&, virtual_ptr<Animal>), void);
 
 BOOST_OPENMETHOD_OVERRIDE(
-    trick, (std::ostream & os, virtual_ptr<Dog> /*dog*/), void) {
+    trick, (std::ostream& os, virtual_ptr<Dog> /*dog*/), void) {
     os << "spin\n";
 }
 

doc/modules/ROOT/examples/virtual_ptr.cpp

@@ -22,12 +22,12 @@ BOOST_OPENMETHOD_CLASSES(Animal, Cat, Dog);
 BOOST_OPENMETHOD(yell, (std::ostream&, virtual_ptr<Animal>), void);
 
 BOOST_OPENMETHOD_OVERRIDE(
-    yell, (std::ostream & os, virtual_ptr<Cat> /*cat*/), void) {
+    yell, (std::ostream& os, virtual_ptr<Cat> /*cat*/), void) {
     os << "hiss";
 }
 
 BOOST_OPENMETHOD_OVERRIDE(
-    yell, (std::ostream & os, virtual_ptr<Dog> /*dog*/), void) {
+    yell, (std::ostream& os, virtual_ptr<Dog> /*dog*/), void) {
     os << "bark";
 }
 
@@ -36,14 +36,14 @@ BOOST_OPENMETHOD(
 
 BOOST_OPENMETHOD_OVERRIDE(
     encounter,
-    (std::ostream & os, virtual_ptr<Dog> dog, virtual_ptr<Cat> /*cat*/), void) {
+    (std::ostream& os, virtual_ptr<Dog> dog, virtual_ptr<Cat> /*cat*/), void) {
     yell(os, dog);
     os << " and chase";
 }
 
 BOOST_OPENMETHOD_OVERRIDE(
     encounter,
-    (std::ostream & os, virtual_ptr<Cat> cat, virtual_ptr<Dog> /*dog*/), void) {
+    (std::ostream& os, virtual_ptr<Cat> cat, virtual_ptr<Dog> /*dog*/), void) {
     yell(os, cat);
     os << " and run";
 }