1 .. include:: ../disclaimer-zh_CN.rst 2 3 :Original: Documentation/doc-guide/kernel-doc.rst 4 5 :译者: 吴想成 Wu XiangCheng <bobwxc@email.cn> 6 7 编写kernel-doc注释 8 ================== 9 10 Linux内核源文件可以包含kernel-doc格式的结构化文档注释,用以描述代码的函数、 11 类型和设计。将文档嵌入源文件更容易保持文档最新。 12 13 .. note:: 内核文档格式与javadoc、gtk-doc或Doxygen看似很相似,但由于历史原因, 14 实际有着明显的不同。内核源包含成千上万个kernel-doc注释。请坚持遵循 15 此处描述的风格。 16 17 .. note:: kernel-doc无法包含Rust代码:请参考 Documentation/rust/general-information.rst 。 18 19 从注释中提取kernel-doc结构,并从中生成适当的 `Sphinx C 域`_ 函数和带有锚点的 20 类型描述。这些注释将被过滤以生成特殊kernel-doc高亮和交叉引用。详见下文。 21 22 .. _Sphinx C 域: http://www.sphinx-doc.org/en/stable/domains.html 23 24 使用 ``EXPORT_SYMBOL`` 或 ``EXPORT_SYMBOL_GPL`` 导出到可加载模块的每个函数都 25 应该有一个kernel-doc注释。模块使用的头文件中的函数和数据结构也应该有 26 kernel-doc注释。 27 28 对于其他内核文件(未标记为 ``static`` )中外部可见的函数,提供kernel-doc格式 29 的文档是一个很好的实践。我们也建议为私有(文件 ``static`` )程序提供kernel-doc 30 格式的文档,以确保内核源代码布局的一致性。此建议优先级较低,由内核源文件的 31 维护者自行决定。 32 33 如何格式化kernel-doc注释 34 ------------------------ 35 36 kernel-doc注释用 ``/**`` 作为开始标记。 ``kernel-doc`` 工具将提取以这种方式 37 标记的注释。注释其余部分的格式类似于一个普通的多行注释,左侧有一列星号,以 38 ``*/`` 行结束。 39 40 函数和类型的kernel-doc注释应该放在所描述的函数或类型之前,以便最大限度地提高 41 更改代码的人同时更改文档的可能性。概述kernel-doc注释可以放在最顶部的任何地方。 42 43 用详细模式和不生成实际输出来运行 ``kernel-doc`` 工具,可以验证文档注释的格式 44 是否正确。例如:: 45 46 scripts/kernel-doc -v -none drivers/foo/bar.c 47 48 当请求执行额外的gcc检查时,内核构建将验证文档格式:: 49 50 make W=n 51 52 函数文档 53 -------- 54 55 函数和函数式宏的kernel-doc注释的一般格式是:: 56 57 /** 58 * 函数名() - 函数简要说明. 59 * @参数1: 描述第一个参数. 60 * @参数2: 描述第二个参数. 61 * 可以为参数提供一段 62 * 多行描述. 63 * 64 * 更详细的描述,进一步讨论函数 函数名(), 这可能对使用或修改它的人有用. 65 * 以空注释行开始, 内部可以包含空注释行. 66 * 67 * 详细描述可以有多个段落. 68 * 69 * Context: 描述函数是否可以休眠, 它需要、释放或期望持有什么锁. 70 * 可以写多行. 71 * Return: 描述函数返回值. 72 * 73 * 返回值描述也可以有多个段落, 74 * 并且应该放在注释块的末尾. 75 */ 76 77 函数名后面的简短描述可以跨多行,并以参数描述、空注释行或注释块结尾结束。 78 79 函数参数 80 ~~~~~~~~ 81 82 每个函数参数都应该按照顺序描述,紧跟在函数简要说明之后。不要在函数描述和参数 83 之间,也不要在参数之间留空。 84 85 每个 ``@参数:`` 描述可以跨多行。 86 87 .. note:: 88 89 如果 ``@参数`` 描述有多行,则说明的续行应该从上一行的同一列开始:: 90 91 * @参数: 较长说明 92 * 的续行 93 94 或:: 95 96 * @参数: 97 * 较长说明 98 * 的续行 99 100 如果函数的参数数目可变,则需用kernel-doc格式对其进行描述:: 101 102 * @...: 描述 103 104 函数上下文 105 ~~~~~~~~~~ 106 107 可调用函数的上下文应该在 ``Context`` 节中描述。此节应该包括函数是休眠的还是 108 可以从中断上下文调用的,以及它需要什么锁、释放什么锁和期望它的调用者持有什么 109 锁。 110 111 例如:: 112 113 * Context: Any context. 114 * Context: Any context. Takes and releases the RCU lock. 115 * Context: Any context. Expects <lock> to be held by caller. 116 * Context: Process context. May sleep if @gfp flags permit. 117 * Context: Process context. Takes and releases <mutex>. 118 * Context: Softirq or process context. Takes and releases <lock>, BH-safe. 119 * Context: Interrupt context. 120 121 返回值 122 ~~~~~~ 123 124 如有返回值,应在 ``Return`` 节中描述。 125 126 .. note:: 127 128 #) 您提供的多行描述文本 *不会* 识别换行符,因此如果您想将某些文本预格式化, 129 如:: 130 131 * Return: 132 * 0 - OK 133 * -EINVAL - invalid argument 134 * -ENOMEM - out of memory 135 136 它们在最终文档中变成一行:: 137 138 Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory 139 140 因此,为了在需要的地方换行,您需要使用ReST列表,例如:: 141 142 * Return: 143 * * 0 - OK to runtime suspend the device 144 * * -EBUSY - Device should not be runtime suspended 145 146 #) 如果您提供的描述性文本中的行以某个后跟冒号的短语开头,则每一个这种短语 147 都将被视为新的节标题,可能会产生意料不到的效果。 148 149 结构体、共用体、枚举类型文档 150 ---------------------------- 151 152 结构体(struct)、共用体(union)、枚举(enum)类型kernel-doc注释的一般格式为:: 153 154 /** 155 * struct 结构体名 - 简要描述. 156 * @成员1: 成员1描述. 157 * @成员2: 成员2描述. 158 * 可以为成员提供 159 * 多行描述. 160 * 161 * 结构体的描述. 162 */ 163 164 可以用 ``union`` 或 ``enum`` 替换上面示例中的 ``struct`` ,以描述共用体或枚举。 165 ``成员`` 用于表示枚举中的元素或共用体成员。 166 167 结构体名称后面的简要说明可以跨多行,并以成员说明、空白注释行或注释块结尾结束。 168 169 成员 170 ~~~~ 171 172 结构体、共用体和枚举的成员应以与函数参数相同的方式记录;它们后紧跟简短的描述, 173 并且为多行。 174 175 在结构体或共用体描述中,可以使用 ``private:`` 和 ``public:`` 注释标签。 176 ``private:`` 域内的字段不会列在生成的文档中。 177 178 ``private:`` 和 ``public:`` 标签必须紧跟在 ``/*`` 注释标记之后。可以选择是否 179 在 ``:`` 和 ``*/`` 结束标记之间包含注释。 180 181 例子:: 182 183 /** 184 * struct 张三 - 简短描述 185 * @a: 第一个成员 186 * @b: 第二个成员 187 * @d: 第三个成员 188 * 189 * 详细描述 190 */ 191 struct 张三 { 192 int a; 193 int b; 194 /* private: 仅内部使用 */ 195 int c; 196 /* public: 下一个是公有的 */ 197 int d; 198 }; 199 200 嵌套的结构体/共用体 201 ~~~~~~~~~~~~~~~~~~~ 202 203 嵌套的结构体/共用体可像这样记录:: 204 205 /** 206 * struct nested_foobar - a struct with nested unions and structs 207 * @memb1: first member of anonymous union/anonymous struct 208 * @memb2: second member of anonymous union/anonymous struct 209 * @memb3: third member of anonymous union/anonymous struct 210 * @memb4: fourth member of anonymous union/anonymous struct 211 * @bar: non-anonymous union 212 * @bar.st1: struct st1 inside @bar 213 * @bar.st2: struct st2 inside @bar 214 * @bar.st1.memb1: first member of struct st1 on union bar 215 * @bar.st1.memb2: second member of struct st1 on union bar 216 * @bar.st2.memb1: first member of struct st2 on union bar 217 * @bar.st2.memb2: second member of struct st2 on union bar 218 */ 219 struct nested_foobar { 220 /* Anonymous union/struct*/ 221 union { 222 struct { 223 int memb1; 224 int memb2; 225 }; 226 struct { 227 void *memb3; 228 int memb4; 229 }; 230 }; 231 union { 232 struct { 233 int memb1; 234 int memb2; 235 } st1; 236 struct { 237 void *memb1; 238 int memb2; 239 } st2; 240 } bar; 241 }; 242 243 .. note:: 244 245 #) 在记录嵌套结构体或共用体时,如果结构体/共用体 ``张三`` 已命名,则其中 246 的成员 ``李四`` 应记录为 ``@张三.李四:`` 247 248 #) 当嵌套结构体/共用体是匿名的时,其中的成员 ``李四`` 应记录为 ``@李四:`` 249 250 行间注释文档 251 ~~~~~~~~~~~~ 252 253 结构成员也可在定义时以行间注释形式记录。有两种样式,一种是单行注释,其中开始 254 ``/**`` 和结束 ``*/`` 位于同一行;另一种是多行注释,开头结尾各自位于一行,就 255 像所有其他核心文档注释一样:: 256 257 /** 258 * struct 张三 - 简短描述. 259 * @张三: 成员张三. 260 */ 261 struct 张三 { 262 int 张三; 263 /** 264 * @李四: 成员李四. 265 */ 266 int 李四; 267 /** 268 * @王五: 成员王五. 269 * 270 * 此处,成员描述可以为好几段. 271 */ 272 int 王五; 273 union { 274 /** @儿子: 单行描述. */ 275 int 儿子; 276 }; 277 /** @赵六: 描述@张三里面的结构体@赵六 */ 278 struct { 279 /** 280 * @赵六.女儿: 描述@张三.赵六里面的@女儿 281 */ 282 int 女儿; 283 } 赵六; 284 }; 285 286 Typedef文档 287 ----------- 288 289 Typedef的kernel-doc文档注释的一般格式为:: 290 291 /** 292 * typedef 类型名称 - 简短描述. 293 * 294 * 类型描述. 295 */ 296 297 还可以记录带有函数原型的typedef:: 298 299 /** 300 * typedef 类型名称 - 简短描述. 301 * @参数1: 参数1的描述 302 * @参数2: 参数2的描述 303 * 304 * 类型描述. 305 * 306 * Context: 锁(Locking)上下文. 307 * Return: 返回值的意义. 308 */ 309 typedef void (*类型名称)(struct v4l2_ctrl *参数1, void *参数2); 310 311 高亮与交叉引用 312 -------------- 313 314 在kernel-doc注释的描述文本中可以识别以下特殊模式,并将其转换为正确的 315 reStructuredText标记和 `Sphinx C 域`_ 引用。 316 317 .. attention:: 以下内容 **仅** 在kernel-doc注释中识别, **不会** 在普通的 318 reStructuredText文档中识别。 319 320 ``funcname()`` 321 函数引用。 322 323 ``@parameter`` 324 函数参数的名称(未交叉引用,仅格式化)。 325 326 ``%CONST`` 327 常量的名称(未交叉引用,仅格式化)。 328 329 ````literal```` 330 预格式化文本块。输出将使用等距字体。 331 332 若你需要使用在kernel-doc脚本或reStructuredText中有特殊含义的字符,则此功能 333 非常有用。 334 335 若你需要在函数描述中使用类似于 ``%ph`` 的东西,这特别有用。 336 337 ``$ENVVAR`` 338 环境变量名称(未交叉引用,仅格式化)。 339 340 ``&struct name`` 341 结构体引用。 342 343 ``&enum name`` 344 枚举引用。 345 346 ``&typedef name`` 347 Typedef引用。 348 349 ``&struct_name->member`` or ``&struct_name.member`` 350 结构体或共用体成员引用。交叉引用将链接到结构体或共用体定义,而不是直接到成员。 351 352 ``&name`` 353 泛类型引用。请首选上面描述的完整引用方式。此法主要是为了可能未描述的注释。 354 355 从reStructuredText交叉引用 356 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 357 358 无需额外的语法来从reStructuredText文档交叉引用kernel-do注释中定义的函数和类型。 359 只需以 ``()`` 结束函数名,并在类型之前写上 ``struct`` , ``union`` , ``enum`` 360 或 ``typedef`` 。 361 例如:: 362 363 See foo(). 364 See struct foo. 365 See union bar. 366 See enum baz. 367 See typedef meh. 368 369 若要在交叉引用链接中使用自定义文本,可以通过以下语法进行:: 370 371 See :c:func:`my custom link text for function foo <foo>`. 372 See :c:type:`my custom link text for struct bar <bar>`. 373 374 有关更多详细信息,请参阅 `Sphinx C 域`_ 文档。 375 376 总述性文档注释 377 -------------- 378 379 为了促进源代码和注释紧密联合,可以将kernel-doc文档块作为自由形式的注释,而 380 不是函数、结构、联合、枚举或typedef的绑定kernel-doc。例如,这可以用于解释 381 驱动程序或库代码的操作理论。 382 383 这是通过使用带有节标题的 ``DOC:`` 节关键字来实现的。 384 385 总述或高层级文档注释的一般格式为:: 386 387 /** 388 * DOC: Theory of Operation 389 * 390 * The whizbang foobar is a dilly of a gizmo. It can do whatever you 391 * want it to do, at any time. It reads your mind. Here's how it works. 392 * 393 * foo bar splat 394 * 395 * The only drawback to this gizmo is that is can sometimes damage 396 * hardware, software, or its subject(s). 397 */ 398 399 ``DOC:`` 后面的标题用作源文件中的标题,但也用作提取文档注释的标识符。因此, 400 文件中的标题必须是唯一的。 401 402 包含kernel-doc注释 403 ================== 404 405 文档注释可以被包含在任何使用专用kernel-doc Sphinx指令扩展的reStructuredText 406 文档中。 407 408 kernel-doc指令的格式如下:: 409 410 .. kernel-doc:: source 411 :option: 412 413 *source* 是相对于内核源代码树的源文件路径。 414 支持以下指令选项: 415 416 export: *[source-pattern ...]* 417 包括 *source* 中使用 ``EXPORT_SYMBOL`` 或 ``EXPORT_SYMBOL_GPL`` 导出的所有 418 函数的文档,无论是在 *source* 中还是在 *source-pattern* 指定的任何文件中。 419 420 当kernel-doc注释被放置在头文件中,而 ``EXPORT_SYMBOL`` 和 ``EXPORT_SYMBOL_GPL`` 421 位于函数定义旁边时, *source-pattern* 非常有用。 422 423 例子:: 424 425 .. kernel-doc:: lib/bitmap.c 426 :export: 427 428 .. kernel-doc:: include/net/mac80211.h 429 :export: net/mac80211/*.c 430 431 internal: *[source-pattern ...]* 432 包括 *source* 中所有在 *source* 或 *source-pattern* 的任何文件中都没有使用 433 ``EXPORT_SYMBOL`` 或 ``EXPORT_SYMBOL_GPL`` 导出的函数和类型的文档。 434 435 例子:: 436 437 .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c 438 :internal: 439 440 identifiers: *[ function/type ...]* 441 在 *source* 中包含每个 *function* 和 *type* 的文档。如果没有指定 *function* , 442 则 *source* 中所有函数和类型的文档都将包含在内。 443 444 例子:: 445 446 .. kernel-doc:: lib/bitmap.c 447 :identifiers: bitmap_parselist bitmap_parselist_user 448 449 .. kernel-doc:: lib/idr.c 450 :identifiers: 451 452 no-identifiers: *[ function/type ...]* 453 排除 *source* 中所有 *function* 和 *type* 的文档。 454 455 例子:: 456 457 .. kernel-doc:: lib/bitmap.c 458 :no-identifiers: bitmap_parselist 459 460 functions: *[ function/type ...]* 461 这是“identifiers”指令的别名,已弃用。 462 463 doc: *title* 464 包含 *source* 中由 *title* 标题标识的 ``DOC:`` 文档段落。 *title* 中允许 465 空格;不要在 *title* 上加引号。 *title* 仅用作段落的标识符,不包含在输出中。 466 请确保在所附的reStructuredText文档中有适当的标题。 467 468 例子:: 469 470 .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c 471 :doc: High Definition Audio over HDMI and Display Port 472 473 如果没有选项,kernel-doc指令将包含源文件中的所有文档注释。 474 475 kernel-doc扩展包含在内核源代码树中,位于 ``Documentation/sphinx/kerneldoc.py`` 。 476 在内部,它使用 ``scripts/kernel-doc`` 脚本从源代码中提取文档注释。 477 478 .. _kernel_doc_zh: 479 480 如何使用kernel-doc生成手册(man)页 481 ----------------------------------- 482 483 如果您只想使用kernel-doc生成手册页,可以从内核git树这样做:: 484 485 $ scripts/kernel-doc -man \ 486 $(git grep -l '/\*\*' -- :^Documentation :^tools) \ 487 | scripts/split-man.pl /tmp/man 488 489 一些旧版本的git不支持路径排除语法的某些变体。 490 以下命令之一可能适用于这些版本:: 491 492 $ scripts/kernel-doc -man \ 493 $(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \ 494 | scripts/split-man.pl /tmp/man 495 496 $ scripts/kernel-doc -man \ 497 $(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \ 498 | scripts/split-man.pl /tmp/man 499
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.