How to validate whether a c++ program is well documented using Doxygen format or not?

Question

Is there a way for Doxygen to report whether source code is documented or not? Is there any way to identify the set of files which are not well documented in a set of C++ source files?

• Coding Language: C++
• Documentation Tool : Doxygen (This can be changed with some other open tool if it has an option for validation)

/// \brief  Main function
/// \param  argc An integer argument count of the command line arguments
/// \param  argv An argument vector of the command line arguments
/// \return an integer 0 upon exit success
int main(int argc, char** argv)
{
    /// Comments I would like to be documented in as well
    return 0;
}

The command which I have used is as follows

$> doxygen Doxyfile && echo "success" || echo "failed"

Answer 1

Doxygen already provides some useful configuration options:

WARN_IF_UNDOCUMENTED

If the WARN_IF_UNDOCUMENTED tag is set to YES then doxygen will generate warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag will automatically be disabled.

WARN_IF_DOC_ERROR

If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for potential errors in the documentation, such as not documenting some parameters in a documented function, or documenting parameters that don't exist or using markup commands wrongly.

WARN_NO_PARAMDOC

This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that are documented, but have no documentation for their parameters or return value. If set to NO, doxygen will only warn about wrong or incomplete parameter documentation, but not about the absence of documentation. If EXTRACT_ALL is set to YES then this flag will automatically be disabled.

And finally:

WARN_AS_ERROR

If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when a warning is encountered. If the WARN_AS_ERROR tag is set to FAIL_ON_WARNINGS then doxygen will continue running as if WARN_AS_ERROR tag is set to NO, but at the end of the doxygen process doxygen will return with a non-zero status.

Possible values are: NO, YES and FAIL_ON_WARNINGS.

So let's put all this together. The Doxyfile needs to contain the following settings:

# EXTRACT_ALL = NO is needed, or otherwise some of the 
#               other flags are disabled automatically.
EXTRACT_ALL = NO
WARN_IF_UNDOCUMENTED = YES
WARN_IF_DOC_ERROR = YES
WARN_NO_PARAMDOC = YES
# WARN_AS_ERROR could also be NO, but then
# it stops after the first documentation error.
WARN_AS_ERROR = YES

That way doxygen will show all undocumented code and it will exit with a non-zero, if there is undocumented code.