时间戳

首页 > 解决方案 > 如何验证 C++ 程序是否使用 Doxygen 格式有良好的文档记录？

c++ - 如何验证 C++ 程序是否使用 Doxygen 格式有良好的文档记录？

问题描述

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

/// \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"

标签： c++doxygencode-documentation

解决方案

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

WARN_IF_UNDOCUMENTED

如果WARN_IF_UNDOCUMENTED标签设置为YES然后 doxygen 将为无证成员生成警告。如果EXTRACT_ALL设置为，YES则此标志将自动禁用。

WARN_IF_DOC_ERROR

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

WARN_NO_PARAMDOC

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

最后：

WARN_AS_ERROR

如果WARN_AS_ERROR标签设置为YESdoxygen 将在遇到警告时立即停止。如果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 将显示所有未记录的代码，如果有未记录的代码，它将以非零值退出。

推荐阅读