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