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"

Requests for tools are off topic here and should be made the sister site software recommendations. In doxygen there is no such facility except for checking the warnings that doxygen gives — albert, Mar 16 '21 at 17:29
I’m voting to close this question because I think it belongs to Software recommendations. — albert, Mar 16 '21 at 17:30
Not necessarily a software recommendation, one can do it with doxygen. I had an answer almost ready, but the question was closed before I could post it. — Striezel, Mar 16 '21 at 17:32
@Striezel is your answer different from my comment regarding the warnings? — albert, Mar 16 '21 at 17:47
@albert: Yes, doxygen can give a clean non-zero exit code in that case, if configured to do that. That should allow detection of undocumented code in CI pipelines or similar places. — Striezel, Mar 16 '21 at 17:48
So not really different just using the setting `WARN_AS_ERROR=YES` and is still a bit away from what OP wants, he wants a set of files that are not well documented and not the first error and stop (my interpretation), but still it will probably good to know for him. — albert, Mar 16 '21 at 17:51
Depends on how one interprets the question, but basically `WARN_AS_ERROR=FAIL_ON_WARNINGS` and some other settings (`EXTRACT_ALL = NO`, `WARN_IF_UNDOCUMENTED = YES`, `WARN_IF_DOC_ERROR = YES`, `WARN_NO_PARAMDOC = YES`) should do the trick. `WARN_AS_ERROR=FAIL_ON_WARNINGS` is better than just `WARN_AS_ERROR=YES` in that case, because it will not stop after the first warning / undocumented code, but go on to show all further warnings and then finish with a non-zero exit code, if there is undocumented stuff. This should basically show all files with undocumented code as warnings. — Striezel, Mar 16 '21 at 17:57
@Striezel Thank you Striezel for your solution. The tsolution is almost matching with my expectation. It is working as expected when there is mis matching arguments or formats — Thomas Easo, Mar 16 '21 at 18:14
@Striezel Oops I forgot on the possibility I added regarding`WARN_AS_ERROR=FAIL_ON_WARNINGS` — albert, Mar 16 '21 at 18:14
@ThomasEaso I've constrained the question to make it clearly about Doxygen in particular. This is to avoid people (like myself) from assuming it's a software recommendation question. — Ken Wayne VanderLinde, Mar 16 '21 at 18:36

score 5 · Accepted Answer · edited Mar 16 '21 at 19:02

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.

This solution is working. Anyone who is referring to the same problem can be resolved with the above steps. Thank you Striezel — Thomas Easo, Mar 16 '21 at 18:24

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

1 Answers1