Android GKI内核5.15中的kernel-doc注释编写指南

什么是kernel-doc注释

在Android GKI内核5.15项目中，kernel-doc是一种特殊的注释格式，用于为内核代码中的函数、结构体、枚举等元素生成结构化文档。这种注释格式与代码紧密结合，使得文档能够随着代码变更而同步更新，大大提高了文档的维护性。

为什么需要kernel-doc注释

1. 代码文档一体化：文档与代码共存，修改代码时更容易记得更新文档
2. 自动化文档生成：可以通过工具自动提取注释生成API文档
3. 标准化格式：统一的内核文档风格，便于开发者阅读和理解
4. 模块接口说明：特别适合描述导出给模块使用的函数和数据结构

基本语法规则

kernel-doc注释以/**开头，以*/结尾，中间每行以*开头：

/**
 * 这里是注释内容
 * 可以多行
 */

注释应该紧贴在要描述的元素之前，这样代码修改时更容易注意到需要同步更新文档。

函数文档编写规范

函数文档的基本结构如下：

/**
 * 函数名() - 简要描述
 * @参数1: 参数1的描述
 * @参数2: 参数2的描述
 *         (多行描述时后续行对齐)
 *
 * 详细描述部分，可以多段落
 *
 * Context: 调用上下文说明(是否可睡眠、需要的锁等)
 * Return: 返回值说明
 */

参数描述要点

1. 每个参数单独用@参数名:描述
2. 多行描述时后续行要对齐
3. 可变参数用@...:描述

上下文描述

Context部分非常重要，需要明确说明：

• 函数能否在中断上下文中调用
• 是否会睡眠
• 需要调用者持有哪些锁
• 函数内部会获取/释放哪些锁

示例：

/**
 * foo() - 示例函数
 * @bar: 输入参数
 *
 * 这是一个示例函数说明
 *
 * Context: 进程上下文，可能睡眠
 * Return: 成功返回0，失败返回错误码
 */

结构体/联合体/枚举文档

结构体文档格式：

/**
 * struct 结构体名 - 简要描述
 * @成员1: 成员1描述
 * @成员2: 成员2描述
 *
 * 详细描述部分
 */

成员可见性控制

可以使用private:和public:标签控制文档中显示的成员：

struct my_struct {
    int a;    // 会出现在文档中
/* private: 内部使用 */
    int b;    // 不会出现在文档中
/* public: 外部可访问 */
    int c;    // 会出现在文档中
};

嵌套结构体文档

对于嵌套结构体，使用点号表示层级关系：

/**
 * struct outer - 外层结构
 * @inner.member: 内层成员描述
 */
struct outer {
    struct {
        int member;
    } inner;
};

类型定义文档

typedef文档格式：

/**
 * typedef 类型名 - 简要描述
 *
 * 类型详细描述
 */

对于函数指针类型：

/**
 * typedef 类型名 - 简要描述
 * @参数1: 参数1描述
 * @参数2: 参数2描述
 *
 * Context: 调用上下文
 * Return: 返回值说明
 */
typedef int (*type_name)(int 参数1, void *参数2);

高级特性

交叉引用

在文档注释中可以使用特殊语法引用其他元素：

• funcname() - 引用函数
• &struct name - 引用结构体
• &enum name - 引用枚举
• &typedef name - 引用类型定义

概述文档

除了具体的API文档，还可以编写模块或文件的概述文档：

/**
 * DOC: 理论概述
 *
 * 这里是模块或子系统的总体描述
 * 可以包含多段落
 */

文档验证与生成

验证文档格式

在构建时使用以下命令验证文档格式：

make W=n

生成man手册

可以使用内核提供的脚本生成man手册：

scripts/kernel-doc -man $(git grep -l '/\*\*') | scripts/split-man.pl /tmp/man

最佳实践建议

1. 所有导出符号必须文档化：使用EXPORT_SYMBOL导出的函数必须有kernel-doc注释
2. 头文件接口要文档化：会被外部模块使用的头文件中的接口需要完整文档
3. 内部函数建议文档化：即使是static函数也建议添加文档，保持一致性
4. 保持文档更新：修改代码时记得同步更新相关文档
5. 详细说明上下文约束：特别是锁和上下文要求，这对内核开发至关重要

通过遵循这些规范，可以为Android GKI内核5.15项目创建出高质量、可维护的代码文档，极大提高代码的可读性和可维护性。