Skip to content

docs: complete the reference — fill gaps against cppreference and fix the root README #20

Closed

Description

@homer6

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 marks strings/, algorithms/, ranges/, utilities/, language/ as "(planned)" and lists only containers/ in detail. Replace it with the real tree (all 18 library areas + 11 language areas), or point at docs/examples/README.md as 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 in templates-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 in expressions/operators.md) — check cppreference's split first.
  • #embed (C++26) in preprocessor/.
  • 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 in io/ (today only covered inside text-processing/formatting.md).
  • Floating-point environment <cfenv> → numerics/.
  • Null-terminated sequence utilities — byte (<cstring>, <cctype>), multibyte and wide (<cwchar>, <cuchar>, <cwctype>) → strings/ or text-processing/.
  • text_encoding (C++26) — only a mention in localization.md; give it a section or page.
  • Language support leftovers — signals (<csignal>), non-local jumps (<csetjmp>), type_info/typeid/type_index currently live only in language-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 it nocompile/compile-fail with a reason).
  • Each new page follows the house skeleton in CLAUDE.md, cites cppreference only, is added to its area README and docs/examples/README.md, and passes tools/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:

This issue closes when all sub-issues are delivered.

Activity

  1. homer6 commented on Oct 31, 2026

    @homer6
    OwnerAuthor

    All sub-issues are delivered:

    Sub-issue PR
    #22 root README layout + sourcing rule 822a154 (pushed to main)
    #23 language: comments, keywords, jump statements, freestanding, #embed #37
    #24 language: constraints, deducing this, bit-fields, operator overloading #34
    #25 library: debugging, safe reclamation, syncstream, print #32
    #26 library: cfenv, C strings, text_encoding, language support, named requirements #39
    #27 snippets: containers, strings, text-processing (82 fixed) #35
    #28 snippets: algorithms, ranges, iterators, utilities, concepts (80 fixed) #31
    #29 snippets: memory … feature-test macros (113 fixed) #33
    #30 snippets: language (74 fixed) #36

    What changed

    Why

    • Every claim verified locally (GCC 15.2, Homebrew Clang 22 + libc++, Docker GCC 16.2), per the sourcing rule in CLAUDE.md.

    Still open

  2. added a commit that references this issue on Oct 31, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions