C 域¶

版本 1.0 中新增。

C 域（名称为 c）适用于 C API 文档。

.. c:member:: declaration¶

.. c:var:: declaration¶

描述 C 结构体成员或变量。示例签名

.. c:member:: PyObject *PyTypeObject.tp_bases

这两个指令之间的区别仅在于外观。

.. c:function:: function prototype¶

描述 C 函数。签名应按照 C 语言的语法给出，例如：

.. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)

请注意，您不必在签名中使用反斜杠转义星号，因为它不会被 reStructuredText 内联解析器解析。

在函数的描述中，您可以使用以下信息字段（另请参见信息字段列表）。

param、parameter、arg、argument：参数的描述。
type：参数的类型，写法如同传递给 c:expr 角色。
returns、return：返回值的描述。
rtype：返回类型，写法如同传递给 c:expr 角色。
retval、retvals：描述函数结果的 returns 的替代方案。

版本 4.3 中新增： retval 字段类型。

例如

.. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)

   :param type: description of the first parameter.
   :param nitems: description of the second parameter.
   :returns: a result.
   :retval NULL: under some conditions.
   :retval NULL: under some other conditions as well.

呈现为

PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)¶

无内容条目：

无索引条目：

参数：

type – 第一个参数的描述。
nitems – 第二个参数的描述。

返回值：

结果。

返回值：

NULL – 在某些条件下。
NULL – 在其他某些条件下。

:single-line-parameter-list: (no value)¶: 确保函数的参数将输出在一行上，覆盖 c_maximum_signature_line_length 和 maximum_signature_line_length。

版本 7.1 中新增。

.. c:macro:: name¶

.. c:macro:: name(arg list)

描述 C 宏，即 C 语言的 #define，不包含替换文本。

在宏的描述中，您可以使用与 c:function 指令相同的 info 字段。

版本 3.0 中新增：函数风格的变体。

:single-line-parameter-list: (no value)¶: 确保宏的参数将输出在一行上，覆盖 c_maximum_signature_line_length 和 maximum_signature_line_length。

版本 7.1 中新增。

.. c:struct:: name¶: 描述 C 结构体。

版本 3.0 中新增。

.. c:union:: name¶: 描述 C 联合体。

版本 3.0 中新增。

.. c:enum:: name¶: 描述 C 枚举。

版本 3.0 中新增。

.. c:enumerator:: name¶: 描述 C 枚举器。

版本 3.0 中新增。

.. c:type:: typedef-like declaration¶
.. c:type:: name: 描述 C 类型，可以是 typedef，也可以是未指定类型的别名。

交叉引用 C 结构¶

如果以下角色在文档中定义，则会创建到 C 语言结构的交叉引用

:c:member:¶
:c:data:¶
:c:var:¶
:c:func:¶
:c:macro:¶
:c:struct:¶
:c:union:¶
:c:enum:¶
:c:enumerator:¶
:c:type:¶: 引用如上所述定义的 C 声明。请注意，c:member、c:data 和 c:var 是等效的。

版本 3.0 中新增： var、struct、union、enum 和 enumerator 角色。

匿名实体¶

C 语言支持匿名结构体、枚举和联合体。为了方便文档记录，必须为它们指定一个以 @ 开头的名称，例如 @42 或 @data。这些名称也可以用于交叉引用，即使省略嵌套符号也可以找到它们。 @... 名称将始终呈现为 [anonymous]（可能作为链接）。

示例

.. c:struct:: Data

   .. c:union:: @data

      .. c:var:: int a

      .. c:var:: double b

Explicit ref: :c:var:`[email protected]`. Short-hand ref: :c:var:`Data.a`.

这将呈现为

struct Data¶

union [anonymous]¶

int a¶

double b¶

显式引用：Data.[anonymous].a。简写引用：Data.a。

版本 3.0 中新增。

别名声明¶

有时，在其他地方列出声明可能会有帮助，例如，在创建接口摘要时。以下指令可用于此目的。

.. c:alias:: name¶

插入一个或多个别名声明。每个实体都可以像在 c:any 角色中一样指定。

例如

.. c:var:: int data
.. c:function:: int f(double k)

.. c:alias:: data
             f

变为

int data¶

int f(double k)¶

int data
int f(double k)

版本 3.2 中新增。

选项

:maxdepth: int¶: 也插入嵌套声明，直至给定的总深度。使用 0 表示无限深度，使用 1 表示仅提及的声明。默认为 1。

版本 3.3 中新增。

:noroot:¶: 跳过提及的声明，仅呈现嵌套声明。需要 maxdepth 为 0 或至少为 2。

版本 3.5 中新增。

内联表达式和类型¶

:c:expr:¶

:c:texpr:¶

将 C 表达式或类型插入为内联代码（cpp:expr）或内联文本（cpp:texpr）。例如

.. c:var:: int a = 42

.. c:function:: int f(int i)

An expression: :c:expr:`a * f(a)` (or as text: :c:texpr:`a * f(a)`).

A type: :c:expr:`const Data*`
(or as text :c:texpr:`const Data*`).

将呈现如下

int a = 42¶

int f(int i)¶

表达式：a * f(a)（或作为文本：a * f(a)）。

类型：const Data*（或作为文本 const Data*）。

版本 3.0 中新增。

命名空间¶

版本 3.1 中新增。

C 语言本身不支持命名空间，但在文档中模拟它有时很有用，例如，显示备用声明。此功能也可用于记录结构体/联合体/枚举的成员与其父声明分开。

可以使用三个命名空间指令更改当前范围。它们管理一个声明栈，其中 c:namespace 重置栈并更改给定范围。

c:namespace-push 指令将范围更改为当前范围的给定内部范围。

c:namespace-pop 指令撤消最近的 c:namespace-push 指令。

.. c:namespace:: scope specification¶

将后续对象的当前范围更改为给定范围，并重置命名空间指令栈。请注意，可以通过点分隔符指定嵌套范围，例如

.. c:namespace:: Namespace1.Namespace2.SomeStruct.AnInnerStruct

所有后续对象都将被定义为它们的名称是否已声明并带有前缀范围。将从当前范围开始搜索后续交叉引用。

使用 NULL 或 0 作为范围将更改为全局范围。

.. c:namespace-push:: scope specification¶

相对于当前范围更改范围。例如，在

.. c:namespace:: A.B

.. c:namespace-push:: C.D

之后，当前范围将为 A.B.C.D。

.. c:namespace-pop::¶

撤消之前的 c:namespace-push 指令（不是仅弹出范围）。例如，在

.. c:namespace:: A.B

.. c:namespace-push:: C.D

.. c:namespace-pop::

之后，当前范围将为 A.B（不是 A.B.C）。

如果之前没有使用 c:namespace-push 指令，但仅使用了 c:namespace 指令，则当前范围将重置为全局范围。也就是说，.. c:namespace:: A.B 等效于

.. c:namespace:: NULL

.. c:namespace-push:: A.B

配置变量¶

请参阅 C 域的选项。