如何验证 C++ 程序是否使用 Doxygen 格式记录良好？

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 已经提供了一些有用的configuration options:

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 标签设置为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 将显示所有未记录的代码，如果有未记录的代码，它将以非零值退出。