doxygen "warning: documented symbol was not declared or defined"

TL;DR: Make the documented declaration match the real one exactly. Doxygen warns "documented symbol was not declared or defined" when a comment documents a function, class, or variable it cannot find - usually the signature changed, the symbol moved namespaces, or the comment sits above the wrong declaration. Update the comment or move it to the real declaration, then re-run doxygen.

warning: documented symbol 'renderPage' was not declared or defined

1. Capture the warnings:

   doxygen Doxyfile 2>&1 | grep "not declared or defined"

   Expected: one line per stale comment, each naming the symbol doxygen could not find.

2. Open the file and compare the documented signature against the actual declaration: parameter types and order, const qualifiers, and the enclosing namespace or class.
3. Fix the mismatch: update the comment to the real signature, or move the comment block to the declaration doxygen should document.

4. Re-run and compare counts:

   doxygen Doxyfile 2>&1 | grep -c "not declared or defined"

   Expected: the count drops to zero.

5. If the symbol sits behind a preprocessor guard, confirm ENABLE_PREPROCESSING is on and the guard macro is enabled for the docs build.

Use this when

• doxygen prints "documented symbol ... was not declared or defined"
• Docs for a function vanished after a refactor
• A comment block documents an overload that no longer exists

Not for this skill when

• The warning is "unable to resolve reference" - that is a backslash-ref target problem, a different fix
• The symbol is intentionally undocumented - remove the stale comment instead
• doxygen cannot find the file at all - check INPUT and FILE_PATTERNS

Variant phrasings

• "doxygen documented symbol not declared or defined"
• "warning: documented symbol"
• "doxygen comment does not match declaration"

Why it happens

Doxygen attaches each comment block to a declaration by matching the documented name and signature against what the parser saw. When a refactor changes the signature, moves the symbol, or deletes it, the comment is left pointing at nothing, and doxygen warns instead of silently dropping it.

Edge cases

• Overloaded functions: each overload needs its own matching comment, or document the one overload users should call.
• Anonymous namespaces and static functions are invisible outside their translation unit; document them where they are defined.
• A backslash-fn command with the wrong signature produces the same warning - the command text must match the real declaration.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_enbzx7y9BmqcWBXdq4WIgw