# Add Doxygen API Docs to a CMake C++ Library

Yes. An agent documents your C++ library's public classes, adds a CMake docs target that builds with zero Doxygen warnings, publishes it to GitHub Pages, opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-doxygen-docs/cmake/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent clones the repository into its own cloud sandbox and reads how the project is built and what its public surface is. In a header-only library like jarro2783/cxxopts, everything lives in `include/cxxopts.hpp`, 3,192 lines with no `///` or `/** */` comment on any public symbol; the README is the only API reference, organised by example (Basics, Positional Arguments, Default and implicit values, Custom help). `CMakeLists.txt` declares `cmake_minimum_required(VERSION 3.5...3.19)`, includes `cmake/cxxopts.cmake`, reads the version from the `CXXOPTS__VERSION_*` defines in the header, defines an `INTERFACE` target aliased `cxxopts::cxxopts`, and gates examples, tests, install and warnings behind `CXXOPTS_BUILD_EXAMPLES`, `CXXOPTS_BUILD_TESTS`, `CXXOPTS_ENABLE_INSTALL` and `CXXOPTS_ENABLE_WARNINGS`, each defaulting to on only when the project is built standalone. The `.gitignore` already lists `Doxyfile`, `docs/` and `doxygen.log`, which says someone ran Doxygen by hand once and never checked anything in.

It adds a `CXXOPTS_BUILD_DOCS` option in the same style as the existing ones and a `doc/CMakeLists.txt` that calls `find_package(Doxygen)`, fails with a clear message when the option is on and Doxygen is absent, and configures `doc/Doxyfile.in` with `configure_file` into the build tree. A template is used rather than `doxygen_add_docs` because that helper arrived in CMake 3.9 and the project promises 3.5. The template sets `INPUT` to the header and `README.md`, `USE_MDFILE_AS_MAINPAGE = README.md` so the existing examples become the front page, `EXTRACT_ALL = NO`, `WARN_IF_UNDOCUMENTED = YES`, `WARN_AS_ERROR = FAIL_ON_WARNINGS` so an undocumented public symbol fails the build, `EXCLUDE_SYMBOLS` for the implementation namespaces, and `PREDEFINED` for `CXXOPTS_USE_UNICODE` so the ICU variant's declarations are seen too. The ignored `Doxyfile` and `docs/` paths are left in `.gitignore`; the checked-in files live under `doc/` and output goes to the build directory.

The bulk of the work is the comments. The agent documents the public API in `///` form: the `Options` class and its builder calls (`add_options`, `parse`, `help`, `positional_help`, `show_positional_help`, `parse_positional`, `allow_unrecognised_options`, `set_width`, `set_tab_expansion`, `custom_help`), `OptionAdder::operator()`, `ParseResult` with `count`, `has`, `operator[]`, `as<T>`, `unmatched` and `arguments`, the `value<T>()` factory with `default_value` and `implicit_value`, and the exception hierarchy from `specification` and `parsing` down to `no_such_option`, `missing_argument` and `incorrect_argument_type`. Each comment says what the call does, what it returns and which exception it throws, in a sentence or two, because a lightweight header should not double in size for the sake of prose. Detail classes get no comments and stay excluded.

It installs `doxygen` and `graphviz` in the sandbox, configures with `-DCXXOPTS_BUILD_DOCS=ON`, builds the `docs` target until Doxygen reports no warnings, then builds the default configuration and runs `ctest` in `build/test` to show the comments changed nothing about the code the `-Wall -Werror -Weffc++` warning set compiles. Last, it adds `.github/workflows/docs.yml`: on push to the default branch, build the docs target and publish `build/doc/html` with `actions/upload-pages-artifact` and `actions/deploy-pages` under `pages: write` and `id-token: write` permissions.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add Doxygen API documentation to this CMake C++ library. Read CMakeLists.txt, the cmake/ helpers and the public header first and list the public classes and functions. Add a CXXOPTS_BUILD_DOCS style option, a doc/CMakeLists.txt that finds Doxygen and configures a doc/Doxyfile.in template compatible with the project's minimum CMake version, with the README as the main page, undocumented public symbols treated as errors and implementation namespaces excluded. Write concise /// comments for every public class, method, factory function and exception type, describing behaviour, return value and thrown exceptions, without documenting internal detail types. Install Doxygen in the sandbox, build the docs target until it reports zero warnings, then build and run the existing tests to show nothing else changed. Add a GitHub Actions workflow that builds the docs on push to the default branch and deploys them to GitHub Pages. Open a pull request listing the documented symbols and the Pages setting the maintainer must enable.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request that changes `CMakeLists.txt` and `include/cxxopts.hpp`, and adds `doc/CMakeLists.txt`, `doc/Doxyfile.in` and `.github/workflows/docs.yml`. The header diff is comments only, and the description lists every symbol that gained one, grouped by class, so a reviewer can scan for a public call that was missed rather than reading the whole diff.

The run's record keeps the Doxygen output from the final clean build, the `cmake --build` and `ctest` output on the default configuration, and the compiler warnings set the project enables, so the claim that nothing but comments changed is backed by a green build in the sandbox.

Before merging, a reviewer reads a few comments for accuracy, since the agent describes behaviour from the code and a maintainer may know an intent the code does not state, enables GitHub Pages with the GitHub Actions source on the repository, and decides whether `docs` should also run on pull requests so a future undocumented symbol is caught before merge.

## Run it on every Linear issue labelled docs

In the console, an automation in the Project that has the repository, with a `linear` trigger on `linear.issue.labeled` and `labels` set to `docs`, starts one run per issue with the issue as context after the prompt; the saved prompt is the whole instruction and the trigger fills in no placeholder. After the first pull request lands, later issues ask for narrower things, a tutorial page for positional arguments or a comment on a new overload, and each run builds the docs target with warnings as errors, so an issue that adds a public symbol without a comment cannot produce a green pull request.

From your own tracker, a handler sends one `POST /o/{org}/sessions` with this body and the repository in `resources`, with a `request_id` that is a UUID v5 of the issue id so a repeated webhook returns the run already started. Set a webhook URL on the API key and Rush posts `run.completed` with the `session_url` when the pull request is up.

## Why run it on Rush?

Documenting a 3,000-line header is tedious and precise at the same time: every comment must match what the code does, the Doxyfile must be tuned until warnings reach zero, and the CMake wiring must respect a minimum version the maintainer chose years ago. The agent does the loop of build, read warnings, fix, rebuild in a sandbox with Doxygen and Graphviz installed, and the record shows the warning count going to zero rather than a promise that it did.

It also proves the non-regression a maintainer cares about most. The sandbox builds the library's own test suite under its own `-Werror` flags after the comments go in, so a stray character in a comment that breaks a compiler is caught before anyone reviews prose.

## Frequently asked questions

### Does this change the header's behaviour or compile time?

No. The only edits to the header are `///` comments, which the preprocessor discards. The run builds the examples and tests with the project's warning flags after the change, and the pull request shows that output. The header grows by the size of the comments, which is why they are kept to a sentence or two each.

### Why a Doxyfile.in instead of doxygen_add_docs?

`doxygen_add_docs` needs CMake 3.9, and a project that declares `cmake_minimum_required(VERSION 3.5...3.19)` should keep working on 3.5. A `configure_file` template works on every version the project supports and makes the Doxygen settings visible in one checked-in file.

### Can the build fail when someone adds an undocumented symbol?

Yes. `WARN_IF_UNDOCUMENTED` with `WARN_AS_ERROR = FAIL_ON_WARNINGS` turns a missing comment on a public symbol into a failed `docs` target. Running that target in CI on pull requests, not only on pushes, is a one-line change to the workflow the reviewer can make.

### Will the docs publish by themselves?

After one manual step: GitHub Pages must be enabled on the repository with GitHub Actions as the source. The workflow has the `pages: write` and `id-token: write` permissions it needs and deploys on every push to the default branch once that setting exists; the pull request names it.

### Does the Meson build need changes?

No. The docs target is CMake-only, gated behind an option that defaults to off for consumers who add the library as a subdirectory, and the Meson workflow keeps building and testing as before. Nothing in `meson.build` references the new `doc/` directory.

## More CMake jobs

- [Add libFuzzer Fuzz Tests to a CMake Project](https://getrush.ai/run/add-fuzz-tests/cmake/)
- [Add GitHub Actions CI to a CMake Project](https://getrush.ai/run/add-github-actions-ci/cmake/)
- [Add Google Benchmark to a CMake Project](https://getrush.ai/run/add-google-benchmark/cmake/)

## More jobs like this: Turn a Linear label into a PR

- [Add a --dry-run Flag to a Click CLI](https://getrush.ai/run/add-dry-run-flag/click/)
- [Add a Durable Object to a Cloudflare Worker](https://getrush.ai/run/add-durable-objects/cloudflare-workers/)
- [Enable DynamoDB Point-in-Time Recovery in an AWS CDK Stack from a Linear Issue](https://getrush.ai/run/add-dynamodb-point-in-time-recovery/aws-cdk/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
