如何确保 C/C++ 代码中不会缺少 doxygen 风格的文档注释？

How to make sure doxygen-style documentation comments aren't missing from C/C++ code?

本文关键字：doxygen 风格 注释 文档 确保 何确保 代码 C++      更新时间：2023-10-16

我想对 C/C++ 代码运行某种 linter 或静态代码分析，如果缺少文档的代码，例如没有 doxygen 样式文档的函数，它会发出警告。换句话说，我想强制执行某些代码标准。我看了一眼clang-tidy和cppcheck，但没有走多远。

为了更清楚地说明我的期望 - 从 Python 开始，我已经习惯了这样的事情：

$ cat test.py 
def answer():
return 42
$ python3 -m pylint test.py 
************* Module test
test.py:1:0: C0111: Missing module docstring (missing-docstring)
test.py:1:0: C0111: Missing function docstring (missing-docstring)
------------------------------------------------------------------
Your code has been rated at 0.00/10 (previous run: 0.00/10, +0.00)

Clang 具有用于静态检查 Doxygen 样式注释的-Wdocumentation选项。 \请参阅 https://clang.llvm.org/docs/UsersManual.html。

此外，正如评论中@Null提到的，doxygen 工具本身会警告某些文档问题。

我最近遇到了这个问题，我实际上使用了doxygen本身+自定义脚本来确保所有文档始终存在。

在 doxygen 配置文件中，启用以下内容：

WARNINGS               = YES
WARN_IF_UNDOCUMENTED   = YES
WARN_IF_DOC_ERROR      = YES
WARN_NO_PARAMDOC       = YES
# Do not throw errors on warning
# otherwise, it will stop on first
# error
WARN_AS_ERROR          = NO
# It will write all warnings to a
# warning file. Make sure to
# add this to your gitignore
WARN_LOGFILE           = doxy.warn
# Optional
QUIET                  = YES

现在，当您运行doxygen命令时，它会将所有错误写入doxy.warn文件中。

现在，我们将解析它并在 doxygen 失败时抛出错误。这是我使用的 shell 脚本(我对 powershell 了解不多;所以，无法为 Windows 提供片段(：

doxygen
CURRENT_DIRECTORY=$(pwd)
# If doxy.warn file is not empty
if [ -s "doxy.warn" ]; then
# Remove the current directory from it to
# make error paths relative and shorter
# lines for better readability
cat doxy.warn | sed "s|${CURRENT_DIRECTORY}|.|"
# Print number warnings
echo "Total: $(wc -l < doxy.warn) documentation warnings"
# Exit with error
exit 1;
else
echo "Documentation is valid!"
exit 0;
fi
相关文章：