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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
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
More jobs like this: Turn a Linear label into a PR
- Add a --dry-run Flag to a Click CLI (Click)
- Add a Durable Object to a Cloudflare Worker (Cloudflare Workers)
- Enable DynamoDB Point-in-Time Recovery in an AWS CDK Stack from a Linear Issue (AWS CDK)