Use this guide when editing a Doxygen block, a page under doc/, a snippet or example, or a documented public name. The documentation is the Doxygen comments in the headers, the topic pages in doc/*.dox, and the programs under doc/snippets, doc/examples and their contrib/doc counterparts, which the doc target compiles and runs to produce the output the pages embed. Keep the Doxygen block above a changed declaration describing the current behavior, preconditions, and return value, and give a module README that names a moved value the same update.
The documentation job is blocking and easy to miss. Unlike the clang-format, codespell, and clang-tidy jobs, build:linux:docs in ci/build.linux.gitlab-ci.yml is not allow_failure, and doc/Doxyfile.in sets WARN_AS_ERROR = FAIL_ON_WARNINGS_PRINT, so one Doxygen warning fails it. Its rules exclude the default merge-request pipeline: it runs on schedules, web pipelines, a merge request labeled all-tests, and a push to the default branch. A malformed \ref can therefore pass review with green CI and break the pipeline on master after the merge. For changes to Doxygen markup, a cross-reference target, a documented name, or a snippet, build the doc target locally with CI's pinned Doxygen version and report the result. If that validation is unavailable, name the missing coverage before merge.
Recommend affected-tests with the relevant platform labels, or affected-tests with all-platforms, for test coverage as described in ci.md. These labels do not trigger build:linux:docs, so their pipelines cannot replace documentation validation. Do not add all-tests without the user's explicit permission for that label.
The recurring authoring mistake is trailing punctuation absorbed into a cross-reference: a colon directly after \ref name becomes part of the symbol Doxygen tries to resolve, so \ref adjoint: the ... fails while \ref adjoint. The ... resolves. Separate a reference from following prose with a space, comma, or period. Punctuation inside the name itself is fine — \ref MatrixBase::cross() is a qualified symbol, not a glued colon.
The doc target also compiles and runs the configured examples and snippets, by way of the all_snippets and all_examples prerequisites in doc/CMakeLists.txt. A renamed or removed public name breaks the documentation build even when every comment is well formed, so search those directories before changing one. “Configured” is the operative word: contrib/doc/examples/CMakeLists.txt adds its SYCL subdirectory only under EIGEN_TEST_SYCL, which build:linux:docs does not set, so a broken contrib SYCL example leaves this target green. Treat the target as coverage for the sets the configuration actually enables, and check the conditional before citing it as coverage.
EIGEN_BUILD_DOC defaults on for a top-level, non-cross-compiling configuration, but doc is excluded from all and must be named:
cmake --build build --target doc
Doxygen and graphviz must be installed. CI builds a pinned Doxygen from source (ci/scripts/build_and_install_doxygen.sh), so another local version can diagnose a different set of warnings; report the version that produced a local result.