Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 20 additions & 16 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
# Working in cpp-docs

This repo is a learning reference for **all of modern C++** — the language and
the standard library — written as example-driven Markdown. There is **no build
system and no compiler step**; the deliverable is documentation, not a program.
the standard library — written as example-driven Markdown. The deliverable is documentation; every
C++ snippet in it is compile-checked locally (`tools/check_snippets.py`).

We mirror how cppreference organizes the reference and fill it in topic by topic.
**Containers are the current starting point, not the whole scope.** Expect to
grow into strings, algorithms, ranges, utilities, numerics, concurrency, and the
core language over time.
We mirror how cppreference organizes the reference. Every library area and
language area on cppreference's main page now has pages (see
`docs/examples/README.md`); new work fills in detail, fixes mistakes, and keeps
up with new standards.

## Source of truth

Expand Down Expand Up @@ -53,9 +53,14 @@ Each cppreference area is a subfolder under `docs/examples/`:

```
docs/examples/
README.md # master index + progress table
containers/{sequence,associative,unordered,adaptors,views}/
strings/ algorithms/ ranges/ utilities/ language/ ... (added as we go)
README.md # master index + progress table
strings/ text-processing/ algorithms/ ranges/ iterators/ utilities/
memory/ metaprogramming/ numerics/ datetime/ io/ concurrency/
execution/ diagnostics/ language-support/ concepts/
feature-test-macros/ named-requirements/
language/{basic-concepts,expressions,statements,declarations-initialization,
functions,classes,templates,exceptions,coroutines,modules,preprocessor}/
```

Keep `docs/examples/README.md` updated whenever a page is added or finished.
Expand Down Expand Up @@ -107,9 +112,9 @@ Links to the relevant cppreference pages (cppreference.com only).

There is no CI (GitHub Actions is disabled for this repo); run the checks
locally. `tools/check_snippets.py` compiles every ```cpp block with
`-std=c++26 -fsyntax-only -pedantic-errors`. `docs/guidelines/` must pass
cleanly; `docs/examples/` is checked against a list of known failures (see
below). Each block is
`-std=c++26 -fsyntax-only -pedantic-errors`. **Both `docs/guidelines/` and
`docs/examples/` must pass cleanly** — every block compiles, or carries an
honest `nocompile` / `compile-fail` / `needs=` tag. Each block is
compiled after `tools/snippet_prelude.hpp` (common headers and placeholders
like `Widget`, `use()`, `process()`). Tag the fence's info string:

Expand All @@ -134,11 +139,10 @@ python3 tools/check_snippets.py docs/examples --cxx g++-15 -q \
```

Each block has a stable ID, `<file>#<heading-slug>/<n>`, shown next to every
failure. `tools/snippet_baseline/gcc.txt` lists the `docs/examples/` blocks
known to fail on GCC; the run fails on a **new** failure, and on a listed
block that now compiles or no longer exists — so when you fix a snippet,
delete its line (or rerun with `--update-baseline`). The list should only
shrink (#20 drives it to empty).
failure. `tools/snippet_baseline/gcc.txt` (the list of known failures) is
**empty** and must stay that way: fix a failing block or tag it honestly —
never add it to the baseline. The `--baseline` run still guards against stale
entries if one is ever added.

`-fsyntax-only` is more than a parse: on GCC and Clang it catches type errors,
errors in templates that are instantiated, and failed constant evaluation —
Expand Down
33 changes: 18 additions & 15 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,41 +18,44 @@ docs/
README.md # master index and progress
containers/ # sequence, associative, unordered, adaptors, views
strings/ # string, string_view, char_traits
text-processing/ # format/print, charconv, regex, localization
text-processing/ # format, charconv, regex, localization, C strings, text_encoding
algorithms/ # <algorithm>, <numeric>, parallel and ranges algorithms
ranges/ # views, adaptors, factories, range concepts
iterators/ # categories, adaptors, operations
utilities/ # optional, variant, tuple, expected, any, bitset, functional
memory/ # smart pointers, allocators, memory resources
metaprogramming/ # type traits, ratio, integer_sequence, reflection
numerics/ # math, random, complex, bit, SIMD, linalg, valarray
numerics/ # math, random, complex, bit, cfenv, SIMD, linalg, valarray
datetime/ # chrono durations, clocks, calendars, time zones
io/ # streams, files, string streams, filesystem
concurrency/ # threads, mutexes, atomics, futures, coordination
io/ # streams, files, filesystem, print, syncstream
concurrency/ # threads, mutexes, atomics, futures, coordination, safe reclamation
execution/ # senders/receivers (C++26)
diagnostics/ # exceptions, system_error, stacktrace
language-support/ # numeric_limits, <=>, source_location, initializer_list
diagnostics/ # exceptions, system_error, stacktrace, debugging
language-support/ # numeric_limits, <=>, source_location, typeid, signals, setjmp
concepts/ # the standard concepts library
feature-test-macros/ # detecting what your compiler supports
named-requirements/ # Cpp17* requirements and how concepts relate
language/ # the core language
basic-concepts/ # types, object model, storage and linkage, contracts
basic-concepts/ # types, object model, storage, contracts, comments, keywords, freestanding
expressions/ # value categories, operators, conversions, constant expressions
statements/ # selection, iteration
statements/ # selection, iteration, jump statements
declarations-initialization/
functions/ # overloading, default and variadic args, lambdas
classes/ # special members, inheritance, unions and aggregates
templates/ # basics, variadics, specialization and CTAD
classes/ # special members, inheritance, operator overloading, deducing this, bit-fields
templates/ # basics, variadics, specialization and CTAD, constraints
exceptions/ # throw/try/catch, noexcept and exception safety
coroutines/ modules/ preprocessor/
coroutines/ modules/ preprocessor/ # preprocessor includes #embed
guidelines/ # how to use it well (see below)
tools/ # check_snippets.py — compile-checks every ```cpp block
evals/ # test cases for the cpp-guidelines agent skill
.claude/skills/ # cpp-guidelines (apply the guidelines), refresh-guidelines (keep them current)
modules/ # submodules: C++ Core Guidelines, perf-report
```

Work still to do is tracked in [#20](https://github.com/homer6/cpp-docs/issues/20)
(missing topics and snippets that don't compile yet).
Every area on cppreference's main page has pages, and every snippet compiles
(or is tagged with why it can't). A GoogleTest suite that checks each page's
claims at run time is in progress:
[#41](https://github.com/homer6/cpp-docs/issues/41).

## Guidelines

Expand Down Expand Up @@ -96,8 +99,8 @@ python3 tools/check_snippets.py docs/examples --cxx g++-15 -q \
--baseline tools/snippet_baseline/gcc.txt
```

`docs/guidelines/` must pass cleanly. `docs/examples/` is checked against a
list of known failures that should only shrink. Fence tags (`body`,
Both must pass cleanly; the list of known failures
(`tools/snippet_baseline/gcc.txt`) is empty and stays that way. Fence tags (`body`,
`nocompile`, `compile-fail`, `needs=…`) are explained in [`CLAUDE.md`](CLAUDE.md).

## Conventions
Expand Down