如何让Doxygen对无文档注释的文件发出警告？

问题描述 #

使用Doxygen v1.9.8（v1.13.1测试结果一致）为C项目生成文档时，发现完全无文档的文件不会触发警告，但已有文档的文件中未注释内容会正常告警。期望WARN_IF_UNDOCUMENTED = YES时，所有无文档的文件都能触发警告，但实际Doxygen会静默跳过这类文件。

已尝试的配置 #

• 将WARN_IF_UNDOCUMENTED设为YES
• 将EXTRACT_ALL设为NO

示例项目结构 #

test_project/
├── src/
│   ├── documented_file.h
│   ├── partially_documented_file.c
│   ├── undocumented_file.h
│   ├── undocumented_file.c
├── Doxyfile

documented_file.h #

/**
 * @file documented_file.h
 * @brief 
 * @author Your Name
 * @date YYYY-MM-DD
 */
#ifndef DOCUMENTED_FILE_H
#define DOCUMENTED_FILE_H
/// A documented macro.
#define DOCUMENTED_MACRO 42
/// A documented function declaration.
void documented_function();
#endif // DOCUMENTED_FILE_H

partially_documented_file.c #

/**
 * @file partially_documented_file.c
 * @brief 
 * @author Your Name
 * @date YYYY-MM-DD
 */
#include "documented_file.h"
/// A documented function implementation.
void documented_function() {
   // Function logic here
}
// An undocumented function implementation.
void undocumented_function() {
   // Function logic here
}

undocumented_file.c #

#include "undocumented_file.h"
void undocumented_function_in_header() {
   // Function logic here
}

undocumented_file.h #

#ifndef UNDOCUMENTED_FILE_H
#define UNDOCUMENTED_FILE_H
#define UNDOCUMENTED_MACRO 0
void undocumented_function_in_header();
#endif // UNDOCUMENTED_FILE_H

Doxyfile配置 #

# General configuration
PROJECT_NAME = "Test Project"
OUTPUT_DIRECTORY = ./doxygen_output
INPUT = ./src
FILE_PATTERNS = *.c *.h
RECURSIVE = YES
# Warnings
WARNINGS = YES
WARN_IF_UNDOCUMENTED = YES
WARN_NO_PARAMDOC = YES
WARN_LOGFILE = doxygen_warnings.log
# Output formats
GENERATE_HTML = YES
GENERATE_LATEX = NO
# Code extraction
EXTRACT_ALL = NO

当前输出（doxygen_warnings.log） #

/workspace/src/partially_documented_file.c:13: warning: Member undocumented_function() (function) of file partially_documented_file.c is not documented.

期望输出 #

/workspace/src/undocumented_file.c: warning: no documentation found for file undocumented_file.c
/workspace/src/undocumented_file.h: warning: no documentation found for file undocumented_file.h
/workspace/src/partially_documented_file.c:13: warning: Member undocumented_function() (function) of file partially_documented_file.c is not documented.

运行环境配置 #

Dockerfile #

# Use an official Ubuntu image
FROM ubuntu:latest
# Install Doxygen and Graphviz
RUN apt-get update && \
   apt-get install -y doxygen graphviz && \
   rm -rf /var/lib/apt/lists/*
# Set the working directory in the container
WORKDIR /workspace
# Default command to run Doxygen when container starts
CMD ["doxygen", "/workspace/Doxyfile"]

.vscode/tasks.json #

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Run Doxygen in Docker",
            "type": "shell",
            "command": "docker",
            "args": [
                "run",
                "--rm",
                "-v",
                "${workspaceFolder}:/workspace",
                "doxygen-container",
                "doxygen", "/workspace/Doxyfile"
            ],
            "group": "build",
            "problemMatcher": []
        }
    ]
}

问题解答 #

这个行为是Doxygen的默认设计：当EXTRACT_ALL = NO时，Doxygen会忽略完全没有文档的文件（因为没有可提取的文档内容），自然不会触发WARN_IF_UNDOCUMENTED警告。要实现对无文件级文档的文件告警，需要添加以下核心配置：

强制告警无文档文件的配置方案 #

在Doxyfile的警告配置区块中添加或修改以下选项：

# Warnings
WARNINGS = YES
WARN_IF_UNDOCUMENTED = YES
WARN_NO_PARAMDOC = YES
WARN_IF_DOC_ERROR = YES
FILE_DOCS_REQUIRED = YES
WARN_LOGFILE = doxygen_warnings.log

原理说明 #

• FILE_DOCS_REQUIRED = YES：从Doxygen 1.8.0开始支持，强制要求所有被处理的文件必须包含@file文档块，否则直接触发文件级缺失警告
• WARN_IF_DOC_ERROR = YES：确保这类文件级文档缺失的错误被记录到警告日志中
• 保持EXTRACT_ALL = NO即可，既不会提取无文档的代码内容，又能对缺失文件级文档的文件发出警告

内容的提问来源于stack exchange，提问作者billybobjoe