~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

TOMOYO Linux Cross Reference
Linux/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst

Version: ~ [ linux-6.12-rc7 ] ~ [ linux-6.11.7 ] ~ [ linux-6.10.14 ] ~ [ linux-6.9.12 ] ~ [ linux-6.8.12 ] ~ [ linux-6.7.12 ] ~ [ linux-6.6.60 ] ~ [ linux-6.5.13 ] ~ [ linux-6.4.16 ] ~ [ linux-6.3.13 ] ~ [ linux-6.2.16 ] ~ [ linux-6.1.116 ] ~ [ linux-6.0.19 ] ~ [ linux-5.19.17 ] ~ [ linux-5.18.19 ] ~ [ linux-5.17.15 ] ~ [ linux-5.16.20 ] ~ [ linux-5.15.171 ] ~ [ linux-5.14.21 ] ~ [ linux-5.13.19 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.229 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.285 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.323 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.336 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.337 ] ~ [ linux-4.4.302 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.12 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

  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 

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

kernel.org | git.kernel.org | LWN.net | Project Home | SVN repository | Mail admin

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

sflogo.php