如何使用 Doxygen 格式验证 c++ 程序是否有据可查？

Question

Doxygen 有没有办法报告源代码是否记录在案？ 有什么方法可以识别一组 C++ 源文件中没有详细记录的文件集？

• 编码语言：C++
• 文档工具：Doxygen（如果有验证选项，可以使用其他一些开放工具进行更改）

/// \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;
}

我使用的命令如下

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

Answer 1

Doxygen 已经提供了一些有用的配置选项：

WARN_IF_UNDOCUMENTED

如果WARN_IF_UNDOCUMENTED标记设置为YES ，则 doxygen 将为未记录的成员生成警告。 如果EXTRACT_ALL设置为YES ，则此标志将自动禁用。

WARN_IF_DOC_ERROR

如果WARN_IF_DOC_ERROR标签设置为YES ，doxygen 将针对文档中的潜在错误生成警告，例如未在文档 function 中记录某些参数，或记录不存在的参数或错误地使用标记命令。

WARN_NO_PARAMDOC

可以启用此WARN_NO_PARAMDOC选项以获取已记录但没有参数或返回值文档的函数的警告。 如果设置为NO ，doxygen 只会警告错误或不完整的参数文档，但不会警告缺少文档。 如果EXTRACT_ALL设置为YES ，则此标志将自动禁用。

最后：

WARN_AS_ERROR

如果WARN_AS_ERROR标记设置为YES ，则 doxygen 将在遇到警告时立即停止。 如果WARN_AS_ERROR标记设置为FAIL_ON_WARNINGS则 doxygen 将继续运行，就像WARN_AS_ERROR标记设置为NO一样，但在 doxygen 进程结束时，doxygen 将以非零状态返回。

可能的值为： NO 、 YES和FAIL_ON_WARNINGS 。

所以让我们把所有这些放在一起。 Doxyfile 需要包含以下设置：

# 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

这样 doxygen 将显示所有未记录的代码，如果有未记录的代码，它将以非零值退出。