doc: add a troubleshooting page

[jll63]

(Written by Claude Code, on behalf of @jll63.)

#132 is merged, and this branch is rebased onto develop, so the diff now shows only the two doc commits. The page documents the messages #132 added, and one of its examples checks one of them.

Adds a Troubleshooting page (nav: after Shared Libraries, before Reference), salvaged and rewritten from the old fix/doc branch. Its generated outputs were stale and it had factual errors.

The page

• Compilation errors:
  • How gcc, clang and MSVC prefix a static_assert.
  • Three worked cases:
    • The overrider matches no method, with all the causes of cannot find '...' method;
    • The overrider discards const;
    • The class is not polymorphic, with its remedies, among them final_virtual_ptr and its caveat.
• Runtime errors: which checks need runtime_checks and which are always on (not implemented and ambiguous are reported on every call), missing class registrations, missing bases, and calls that cannot be dispatched. Each example uses the already-tested errors_* snippets.
• Message index: every static_assert and runtime message the library emits, grouped by area, each with its cause and remedy.

Every compile-time example is a test. The page includes three doc/modules/ROOT/examples/troubleshooting/compile_fail_*.cpp files, each with an expected-error marker. test/CMakeLists.txt and test/Jamfile now glob that directory too, so a page example whose diagnostic changes fails the build. The MSVC wordings were captured with VS 18 BuildTools.

Supporting changes

• doc/modules/ROOT/snippets/ moves to doc/modules/ROOT/examples/snippets/. Antora ignores module directories outside its families, so a page could not include the snippets. The //! include: markers in the headers and doc/mrdocs.yml follow the move, and the reference pages still render them.
• basics.adoc: removes a dead :exampledir: attribute.
• CLAUDE.md: notes on the doc compile-fail glob and the snippets location.

Verified

• ctest: 209/209 (clang 22).
• b2: exit 0.
• Antora render: no new warnings, no broken anchors, all cpp: links resolve, no MRDOCS leaks.

🤖 Generated with Claude Code

https://claude.ai/code/session_016NKQZ2ktRZ1AjCgSLLeXma

[cppalliance-bot]

An automated preview of the documentation is available at https://133.openmethod.prtest3.cppalliance.org/libs/openmethod/doc/html/index.html

If more commits are pushed to the pull request, the docs will rebuild at the same URL.

2026-10-18 16:53:48 UTC

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.34%. Comparing base (5356efb) to head (5045767).
⚠️ Report is 2 commits behind head on develop.

Additional details and impacted files

@@           Coverage Diff            @@
##           develop     #133   +/-   ##
========================================
  Coverage    92.34%   92.34%           
========================================
  Files           27       27           
  Lines         2234     2234           
  Branches       677      677           
========================================
  Hits          2063     2063           
  Misses         112      112           
  Partials        59       59           

Files with missing lines	Coverage Δ
include/boost/openmethod/core.hpp	91.80% <ø> (ø)
include/boost/openmethod/preamble.hpp	78.57% <ø> (ø)

---

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 5a5e67b...5045767. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.