cachepc-linux

Fork of AMDESE/linux with modifications for CachePC side-channel attack
git clone https://git.sinitax.com/sinitax/cachepc-linux
Log | Files | Refs | README | LICENSE | sfeed.txt

kernel-doc.rst (15687B)


      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
     10Linux内核源文件可以包含kernel-doc格式的结构化文档注释,用以描述代码的函数、
     11类型和设计。将文档嵌入源文件更容易保持文档最新。
     12
     13.. note:: 内核文档格式与javadoc、gtk-doc或Doxygen看似很相似,但由于历史原因,
     14          实际有着明显的不同。内核源包含成千上万个kernel-doc注释。请坚持遵循
     15          此处描述的风格。
     16
     17.. note:: kernel-doc无法包含Rust代码:请参考 Documentation/rust/docs.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注释。模块使用的头文件中的函数和数据结构也应该有
     26kernel-doc注释。
     27
     28对于其他内核文件(未标记为 ``static`` )中外部可见的函数,提供kernel-doc格式
     29的文档是一个很好的实践。我们也建议为私有(文件 ``static`` )程序提供kernel-doc
     30格式的文档,以确保内核源代码布局的一致性。此建议优先级较低,由内核源文件的
     31维护者自行决定。
     32
     33如何格式化kernel-doc注释
     34------------------------
     35
     36kernel-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
    286Typedef文档
    287-----------
    288
    289Typedef的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注释的描述文本中可以识别以下特殊模式,并将其转换为正确的
    315reStructuredText标记和 `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
    408kernel-doc指令的格式如下::
    409
    410  .. kernel-doc:: source
    411     :option:
    412
    413*source* 是相对于内核源代码树的源文件路径。
    414支持以下指令选项:
    415
    416export: *[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
    431internal: *[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
    440identifiers: *[ 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
    452no-identifiers: *[ function/type ...]*
    453  排除 *source* 中所有 *function* 和 *type* 的文档。
    454
    455  例子::
    456
    457    .. kernel-doc:: lib/bitmap.c
    458       :no-identifiers: bitmap_parselist
    459
    460functions: *[ function/type ...]*
    461  这是“identifiers”指令的别名,已弃用。
    462
    463doc: *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
    475kernel-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