How to make sure doxygen-style documentation comments aren't missing from C/C++ code?

Question

I want to run some kind of linter or static code analysis on C/C++ code which gives a warning if there is code with missing documentation, for example a function without its doxygen-style documentation coment. In other words, I want to enforce certain code standards. I had a look into clang-tidy and cppcheck , but didn't get very far.

To make it a little bit clearer what I'm expecting - from Python, I'm used to something like this:

$ cat test.py 
def answer():
    return 42
$ python3 -m pylint test.py 
************* Module test
test.py:1:0: C0111: Missing module docstring (missing-docstring)
test.py:1:0: C0111: Missing function docstring (missing-docstring)

------------------------------------------------------------------
Your code has been rated at 0.00/10 (previous run: 0.00/10, +0.00)

Answer 1

Clang has the -Wdocumentation option for statically checking Doxygen-style comments. \see https://clang.llvm.org/docs/UsersManual.html .

Also, as @Null mentioned in the comments, the doxygen tool itself will warn of certain documentation issues.

Answer 2

I faced this issue recently and I actually used doxygen itself + a custom script to make sure that all the documentation is always present.

In the doxygen config file, enable the following:

WARNINGS               = YES
WARN_IF_UNDOCUMENTED   = YES
WARN_IF_DOC_ERROR      = YES
WARN_NO_PARAMDOC       = YES

# Do not throw errors on warning
# otherwise, it will stop on first
# error
WARN_AS_ERROR          = NO

# It will write all warnings to a
# warning file. Make sure to
# add this to your gitignore
WARN_LOGFILE           = doxy.warn

# Optional
QUIET                  = YES

Now, when you run doxygen command, it will write all errors inside doxy.warn file.

Now, we are going to parse it and throw error if doxygen fails. Here is the shell script that I use (I don't know much about powershell; so, can't provide a snippet for Windows):

doxygen

CURRENT_DIRECTORY=$(pwd)

# If doxy.warn file is not empty
if [ -s "doxy.warn" ]; then
    # Remove the current directory from it to
    # make error paths relative and shorter
    # lines for better readability
    cat doxy.warn | sed "s|${CURRENT_DIRECTORY}|.|"

    # Print number warnings
    echo "Total: $(wc -l < doxy.warn) documentation warnings"

    # Exit with error
    exit 1;
else
    echo "Documentation is valid!"
    exit 0;
fi