doxygen-javadocSkill doxygen-javadoc

Doxygen/Javadoc 技能

生成全面的 API 文档，适用于 C、C++、Java 及其他语言，使用 Doxygen 和 Javadoc 创建交叉引用、调用图和全面的技术文档。

能力

• 为 C/C++/Java 项目配置 Doxygen
• 为 Java 代码库生成 Javadoc
• 创建交叉引用文档
• 生成调用图和依赖可视化
• 分析文档覆盖率
• 支持自定义标签定义
• 多种输出格式（HTML、LaTeX、PDF、XML）
• 与构建系统集成（CMake、Maven、Gradle）

使用方法

当您需要以下功能时调用此技能：

• 文档化 C/C++ 库和应用程序
• 生成 Java API 文档
• 创建带有图表的参考文档
• 设置自动化文档构建
• 分析代码结构和依赖关系

输入

参数	类型	必需	描述
projectPath	string	是	项目的根路径
tool	string	否	doxygen 或 javadoc（自动检测）
sourceDir	string	否	源代码目录（默认：src）
outputDir	string	否	输出目录（默认：docs）
outputFormat	array	否	html, latex, pdf, xml, man
includeGraphs	boolean	否	生成调用/依赖图
configFile	string	否	现有的 Doxyfile 或 pom.xml 路径
coverageReport	boolean	否	生成覆盖率分析

输入示例

{
  "projectPath": "./mylib",
  "tool": "doxygen",
  "sourceDir": "src",
  "outputDir": "docs/api",
  "outputFormat": ["html", "xml"],
  "includeGraphs": true,
  "coverageReport": true
}

输出结构

Doxygen 输出

docs/api/
├── html/
│   ├── index.html           # 主要文档页面
│   ├── annotated.html       # 类/结构列表
│   ├── files.html           # 文件列表
│   ├── modules.html         # 模块分组
│   ├── namespaces.html      # 命名空间文档
│   ├── hierarchy.html       # 类层次结构
│   ├── class_*.html         # 各个类页面
│   ├── struct_*.html        # 结构文档
│   ├── group__*.html        # 模块文档
│   ├── *_8h.html            # 头文件文档
│   └── search/              # 搜索索引
├── xml/
│   ├── index.xml            # XML 索引
│   ├── class_*.xml          # 类 XML
│   └── doxygen-layout.xml   # 布局配置
├── latex/                   # LaTeX 输出（如果启用）
└── coverage.json            # 文档覆盖率

Javadoc 输出

docs/api/
├── index.html               # 包概览
├── overview-summary.html    # 概览页面
├── allclasses-index.html    # 类索引
├── allpackages-index.html   # 包索引
├── com/
│   └── example/
│       └── package/
│           ├── package-summary.html
│           ├── ClassName.html
│           └── ...
├── element-list              # 包列表
└── member-search-index.js    # 搜索数据

Doxygen 文档模式

文件头

/**
 * @file database.h
 * @brief 数据库连接和查询工具。
 *
 * 此模块提供线程安全的数据库连接池
 * 和自动重试逻辑的查询执行。
 *
 * @author 开发团队
 * @date 2026-01-24
 * @version 1.0.0
 *
 * @copyright 版权所有 (c) 2026, 公司名称。
 */

类文档

/**
 * @class ConnectionPool
 * @brief 线程安全的数据库连接池。
 *
 * 管理具有可配置的最小和最大大小的数据库连接池。连接在使用前自动
 * 验证。
 *
 * @tparam Connection 要池化的连接类型
 *
 * @note 此类是线程安全的。
 * @warning 在高负载场景下不要超过 maxConnections。
 *
 * @see Connection
 * @see PoolConfig
 *
 * @code{.cpp}
 * ConnectionPool<MySqlConnection> pool(config);
 * auto conn = pool.acquire();
 * conn->execute("SELECT * FROM users");
 * pool.release(conn);
 * @endcode
 */
template<typename Connection>
class ConnectionPool {
public:
    /**
     * @brief 创建一个新的连接池。
     *
     * @param config 池配置参数
     * @throws ConfigurationError 如果 config 无效
     *
     * @pre config.maxConnections > 0
     * @post 池使用 minConnections 初始化
     */
    explicit ConnectionPool(const PoolConfig& config);

    /**
     * @brief 从池中获取连接。
     *
     * 直到连接可用或超时到期阻塞。
     *
     * @param timeout 最大等待时间（毫秒）
     * @return 获取的连接的共享指针
     * @throws TimeoutError 如果超时内无连接可用
     *
     * @par 线程安全
     * 此方法线程安全。
     */
    std::shared_ptr<Connection> acquire(int timeout = 30000);

    /**
     * @brief 将连接释放回池中。
     *
     * @param conn 要释放的连接
     * @retval true 连接成功返回
     * @retval false 连接无效或池已关闭
     */
    bool release(std::shared_ptr<Connection> conn);
};

函数文档

/**
 * @brief 执行带参数绑定的 SQL 查询。
 *
 * @param[in] query 带占位符的 SQL 查询字符串
 * @param[in] params 要绑定的参数值
 * @param[out] results 查询结果（如果是 SELECT）
 *
 * @return 影响的行数（对于 INSERT/UPDATE/DELETE）
 *
 * @throws QueryError 如果查询执行失败
 * @throws ConnectionError 如果数据库连接丢失
 *
 * @par 示例
 * @code{.cpp}
 * std::vector<std::string> params = {"John", "25"};
 * ResultSet results;
 * int affected = executeQuery(
 *     "SELECT * FROM users WHERE name = ? AND age > ?",
 *     params,
 *     results
 * );
 * @endcode
 *
 * @par 性能
 * 查询准备被缓存以重复执行。
 *
 * @todo 添加对批量参数绑定的支持
 * @bug 大型结果集可能会导致内存问题（见 #123）
 *
 * @since 1.0.0
 * @deprecated 使用 PreparedStatement::execute() 代替
 */
int executeQuery(
    const std::string& query,
    const std::vector<std::string>& params,
    ResultSet& results
);

模块/组文档

/**
 * @defgroup Database 数据库模块
 * @brief 数据库连接和操作。
 *
 * 此模块提供数据库抽象层，支持
 * 多个数据库后端。
 *
 * @{
 */

/**
 * @defgroup Database_Connection 连接管理
 * @brief 连接池化和生命周期。
 */

/**
 * @defgroup Database_Query 查询执行
 * @brief 查询构建和执行。
 */

/** @} */ // 结束 Database 组

Javadoc 文档模式

包文档（package-info.java）

/**
 * 数据库连接和查询工具。
 *
 * <p>此包提供线程安全的数据库操作，具有
 * 连接池化和自动重试逻辑。</p>
 *
 * <h2>使用示例</h2>
 * <pre>{@code
 * ConnectionPool pool = new ConnectionPool.Builder()
 *     .maxConnections(10)
 *     .timeout(Duration.ofSeconds(30))
 *     .build();
 *
 * try (Connection conn = pool.acquire()) {
 *     ResultSet rs = conn.executeQuery("SELECT * FROM users");
 * }
 * }</pre>
 *
 * @author 开发团队
 * @version 1.0.0
 * @since 1.0.0
 * @see com.example.database.ConnectionPool
 */
package com.example.database;

类文档

/**
 * 线程安全的数据库连接池。
 *
 * <p>管理具有可配置的最小和最大大小的数据库连接池。连接在
 * 被分发前进行验证。</p>
 *
 * <h2>线程安全</h2>
 * <p>此类是线程安全的。所有公共方法使用适当的
 * 同步。</p>
 *
 * @param <T> 要池化的连接类型
 *
 * @author John Doe
 * @version 1.0.0
 * @since 1.0.0
 *
 * @see Connection
 * @see PoolConfig
 */
public class ConnectionPool<T extends Connection> implements AutoCloseable {

    /**
     * 使用指定的配置创建连接池。
     *
     * @param config 池配置
     * @throws IllegalArgumentException 如果 config 为空
     * @throws ConfigurationException 如果 config 值无效
     */
    public ConnectionPool(PoolConfig config) {
        // 实现
    }

    /**
     * 从池中获取连接。
     *
     * <p>此方法在连接可用或指定的超时到期时阻塞。</p>
     *
     * @param timeout 等待连接的最大时间
     * @return 来自池的有效连接
     * @throws TimeoutException 如果超时内无连接可用
     * @throws PoolClosedException 如果池已关闭
     */
    public T acquire(Duration timeout) throws TimeoutException {
        // 实现
    }

    /**
     * {@inheritDoc}
     *
     * <p>关闭所有连接并释放资源。</p>
     */
    @Override
    public void close() {
        // 实现
    }
}

方法文档及代码示例

/**
 * 执行参数化的 SQL 查询。
 *
 * <p>参数按提供的顺序绑定。在查询字符串中使用 {@code ?}
 * 作为占位符。</p>
 *
 * <h3>示例</h3>
 * <pre>{@code
 * List<User> users = db.query(
 *     "SELECT * FROM users WHERE age > ? AND status = ?",
 *     List.of(18, "active"),
 *     User.class
 * );
 * }</pre>
 *
 * @param <R> 结果类型
 * @param sql 带 {@code ?} 占位符的 SQL 查询
 * @param params 参数值（顺序）
 * @param resultType 结果映射的类
 * @return 映射结果的列表
 * @throws SQLException 如果查询执行失败
 * @throws MappingException 如果结果映射失败
 *
 * @see #execute(String, List) 用于非 SELECT 查询
 * @since 1.0.0
 */
public <R> List<R> query(String sql, List<?> params, Class<R> resultType)
        throws SQLException {
    // 实现
}

Doxyfile 配置

# Doxyfile 配置

# 项目设置
PROJECT_NAME           = "MyLib"
PROJECT_NUMBER         = "1.0.0"
PROJECT_BRIEF          = "数据库连接库"
PROJECT_LOGO           = logo.png

# 输入设置
INPUT                  = src include
FILE_PATTERNS          = *.c *.cc *.cpp *.h *.hpp
RECURSIVE              = YES
EXCLUDE                = src/test src/vendor
EXCLUDE_PATTERNS       = *_test.cpp *_mock.h

# 输出设置
OUTPUT_DIRECTORY       = docs
GENERATE_HTML          = YES
GENERATE_XML           = YES
GENERATE_LATEX         = NO

# HTML 设置
HTML_OUTPUT            = html
HTML_EXTRA_STYLESHEET  = custom.css
SEARCHENGINE           = YES
DISABLE_INDEX          = NO
GENERATE_TREEVIEW      = YES

# 图设置
HAVE_DOT               = YES
CALL_GRAPH             = YES
CALLER_GRAPH           = YES
CLASS_GRAPH            = YES
COLLABORATION_GRAPH    = YES
INCLUDE_GRAPH          = YES
INCLUDED_BY_GRAPH      = YES
DOT_IMAGE_FORMAT       = svg

# 文档提取
EXTRACT_ALL            = NO
EXTRACT_PRIVATE        = NO
EXTRACT_STATIC         = YES
EXTRACT_LOCAL_CLASSES  = YES

# 警告设置
WARN_IF_UNDOCUMENTED   = YES
WARN_IF_DOC_ERROR      = YES
WARN_NO_PARAMDOC       = YES
WARN_AS_ERROR          = NO

# 预处理
ENABLE_PREPROCESSING   = YES
MACRO_EXPANSION        = YES
PREDEFINED             = DOXYGEN_SKIP

# 自定义命令的别名
ALIASES                = "thread_safe=\par 线程安全
"
ALIASES               += "performance=\par 性能
"

Maven Javadoc 配置

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>3.6.3</version>
    <configuration>
        <source>17</source>
        <show>protected</show>
        <nohelp>true</nohelp>
        <doclint>all,-missing</doclint>
        <additionalOptions>
            <additionalOption>-Xdoclint:none</additionalOption>
        </additionalOptions>
        <links>
            <link>https://docs.oracle.com/en/java/javase/17/docs/api/</link>
        </links>
        <tags>
            <tag>
                <name>apiNote</name>
                <placement>a</placement>
                <head>API 注释：</head>
            </tag>
            <tag>
                <name>implSpec</name>
                <placement>a</placement>
                <head>实现规格：</head>
            </tag>
            <tag>
                <name>implNote</name>
                <placement>a</placement>
                <head>实现注释：</head>
            </tag>
        </tags>
    </configuration>
    <executions>
        <execution>
            <id>attach-javadocs</id>
            <goals>
                <goal>jar</goal>
            </goals>
        </execution>
    </executions>
</plugin>

工作流程

1. 检测项目类型 - 识别 C/C++/Java 项目
2. 定位源代码 - 查找源文件和头文件
3. 生成配置 - 创建 Doxyfile 或配置 Maven
4. 解析注释 - 从源代码中提取文档
5. 生成图表 - 创建调用图（如果启用）
6. 构建输出 - 生成 HTML/PDF/XML
7. 分析覆盖率 - 报告文档空白

依赖

Doxygen

# Ubuntu/Debian
apt-get install doxygen graphviz

# macOS
brew install doxygen graphviz

# Windows (chocolatey)
choco install doxygen.install graphviz

Javadoc

# 包含在 JDK 中
java -version  # 推荐 JDK 11+

最佳实践应用

• 文档化所有公共 API 元素
• 使用 @brief 进行一句话总结
• 为所有参数包含 @param
• 指定 @return 值
• 用 @throws 文档化异常
• 为复杂函数添加 @code 示例
• 使用 @see 进行交叉引用
• 启用未文档项的警告

参考

• Doxygen 手册：https://www.doxygen.nl/manual/
• Javadoc 指南：https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html
• Doxygen 特殊命令：https://www.doxygen.nl/manual/commands.html
• Graphviz：https://graphviz.org/

目标流程

• api-doc-generation.js
• sdk-doc-generation.js
• arch-docs-c4.js
• docs-audit.js