It is too easy to forget to update documentation when refactoring code. I often change the parameters of a function and forget to update the doc doc comment which lives on, wrong and misguiding. In c++-land doxygen is the standard documentation generator and it can be configured to warn when a parameter of a function is not documented. This helps but documenting every single parameter of every single function is hard, especially when developing new features which leads to a high false positive rate.

A finer grained approach that only warns if the documentation comment and the function disagree would be valuable.

Our knight in shining armour today is the -Wdocumentation flag for clang. With this flag enabled the compiler will parse the documentation comments and warn if the method signature does not match the documentation every time you rebuild your project, not simply when you rebuild your documentation.

To enable this feature you can add the following snippet to your CMakeLists.txt file:

if (CMAKE_CXX_COMPILER_ID MATCHES "Clang")
    add_definitions("-Wdocumentation")
endif()

This snippet checks that the compiler is clang and enables the flag.

Alternatively to add the flag to a single target you can use target_compile_options($TARGET PRIVATE -Wdocumentation). This will append the specified flags to the compiler invocation when building the specified target.