Repository navigation
Closed
Description
Every area in docs/examples/README.md is ✅, but the reference doesn't yet cover everything cppreference's main page lists, and the root README.md still describes the old plan.
Gap list from comparing the 124 pages under docs/examples/ with the sections on the cppreference main page (https://en.cppreference.com/w/cpp, checked 2026-10-31 via Perplexity with search_domain_filter: cppreference.com) and grepping the pages for each topic.
Fix
- Root
README.md"Layout" is stale — it marksstrings/,algorithms/,ranges/,utilities/,language/as "(planned)" and lists onlycontainers/in detail. Replace it with the real tree (all 18 library areas + 11 language areas), or point atdocs/examples/README.mdas the index.
Language — missing pages
- Comments and Keywords (both are top-level entries on cppreference; neither has a page).
- Jump statements —
break,continue,return,goto, labels (statements/has only selection and iteration). - Constraints and concepts (language) —
requires-clauses,requires-expressions, abbreviated function templates, subsumption. Today only the concepts library page and a mention intemplates-basics.md. - Explicit object parameters / deducing
this(C++23) — not covered anywhere. - Bit-fields — not covered (belongs under
classes/). - Operator overloading as its own page under
classes/(only mentioned inexpressions/operators.md) — check cppreference's split first. -
#embed(C++26) inpreprocessor/. - Freestanding implementations — what a freestanding implementation must provide, C++26 freestanding additions.
Standard library — missing or thin
- Debugging support
<debugging>(C++26):breakpoint,breakpoint_if_debugging,is_debugger_present→diagnostics/. - Safe reclamation (C++26):
<rcu>,<hazard_pointer>→concurrency/. - Synchronized output
<syncstream>(osyncstream) →io/. - Print functions (C++23
std::print/println) — a page inio/(today only covered insidetext-processing/formatting.md). - Floating-point environment
<cfenv>→numerics/. - Null-terminated sequence utilities — byte (
<cstring>,<cctype>), multibyte and wide (<cwchar>,<cuchar>,<cwctype>) →strings/ortext-processing/. -
text_encoding(C++26) — only a mention inlocalization.md; give it a section or page. - Language support leftovers — signals (
<csignal>), non-local jumps (<csetjmp>),type_info/typeid/type_indexcurrently live only inlanguage-support/README.md; give them pages. - Named requirements — an overview page (Cpp17* requirements and how concepts replaced them).
Quality
- Snippets compile —
docs/examples/has many failing blocks (349 of 464 on the first run). ci(snippets): known-failures baseline and compile-fail tests #17 adds a known-failures baseline; this issue drives it to empty (fix each block or tag itnocompile/compile-failwith a reason). - Each new page follows the house skeleton in
CLAUDE.md, cites cppreference only, is added to its area README anddocs/examples/README.md, and passestools/check_snippets.py.
Out of scope
- Technical specifications (Library Fundamentals TS v2/v3 —
propagate_const,scope_exit,observer_ptr, …; Concurrency TS; TM TS) — experimental, not part of the standard.
Approach
Any source is fine (cppreference, standard draft, papers, vendor docs) as long as each fact is verified locally by compiling/running it. Split into sub-issues, one PR each:
- docs: update the root README layout and guidelines list #22 root README layout + CLAUDE.md sourcing rule
- docs(examples): language — comments, keywords, jump statements, freestanding, #embed #23 language: comments, keywords, jump statements, freestanding,
#embed - docs(examples): language — constraints, deducing this, bit-fields, operator overloading #24 language: constraints, deducing
this, bit-fields, operator overloading - docs(examples): library — debugging, safe reclamation, syncstream, print #25 library: debugging, safe reclamation, syncstream, print
- docs(examples): library — cfenv, C strings, text_encoding, language support, named requirements #26 library: cfenv, C strings, text_encoding, language support, named requirements
- fix(examples): make snippets compile — containers, strings, text-processing #27 snippets: containers, strings, text-processing
- fix(examples): make snippets compile — algorithms, ranges, iterators, utilities, concepts #28 snippets: algorithms, ranges, iterators, utilities, concepts
- fix(examples): make snippets compile — memory, metaprogramming, numerics, datetime, io, concurrency, execution, diagnostics, language-support, feature-test-macros, README #29 snippets: memory … diagnostics, language-support, feature-test macros
- fix(examples): make snippets compile — language #30 snippets: language
This issue closes when all sub-issues are delivered.
Metadata
Metadata
Assignees
Labels
No labels
Activity
homer6 commentedon Oct 31, 2026
All sub-issues are delivered:
main)#embedthis, bit-fields, operator overloadingWhat changed
tools/snippet_baseline/gcc.txtis empty.Why
CLAUDE.md.Still open
CLAUDE.mdagain (owner's request); decide where the operator-overloading page lives (docs(examples): add constraints, deducing this, bit-fields and operator overloading pages #34) and how module snippets are checked (fix(examples): make language snippets compile #36).needs=:hive,inplace_vector,<rcu>/<hazard_pointer>, linalg, parts of simd and execution,<cuchar>on macOS.Merge pull request #49 from homer6/docs/48-post-ship-refresh