Esoteric Tip #5: Finding Undocumented Files with Doxygen

In an effort to practice what I preach, I’ve been spending 15 minutes a day documenting code. I’ve been using Doxygen for all my C++ documentation. One thing that I wanted to do early on was easily identify all the files where I was missing documentation and, if possible, the particular places where documentation was missing. I think I’ve managed to do it (or at least come close).

In my Doxyfile, I’ve got the following lines:

WARNINGS = YES
WARN_IF_UNDOCUMENTED = YES
WARN_IF_DOC_ERROR = YES
WARN_LOGFILE = doxygen_warn.log

This means that Doxygen will generate warnings for undocumented members as well as if the documentation is incomplete or isn’t syntactically correct, and that it will log all warnings to the file doxygen_warn.log.

In order to get a list of undocumented files, I look for warnings about missing documentation, extract the filenames for each warning, and make sure that the list of files doesn’t contain any duplicates:

grep "is not documented" doxygen_warn.log | awk '{print $1}' | sed -E 's/:[0-9]+://g' |
    sort | uniq

In order to further expand that list to include the undocumented members in each file, I do something similar, except I extract the filename and information about the undocumented member instead of just the filename:

grep "is not documented" doxygen_warn.log | sed -E 's/is not documented.//g' |
    cut -d' ' -f 1,3- | sed -E 's/:[0-9]+:/ : /g' | sort

It’s kind of quick and dirty, but it seems to do the job. These commands run automatically whenever I generate documentation. The goal (unreasonable though it may be) is to bring the list of undocumented files down to zero.

No related posts.