c++ - 如何验证 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

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.

最后:

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.

所以让我们把所有这些放在一起。 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 将显示所有未记录的代码，如果存在未记录的代码，它将以非零值退出。