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)¶

No-contents-entry:

No-index-entry:

参数:

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

返回:

一个结果。

返回值:

NULL – 在某些条件下。
NULL – 在某些其他条件下也是如此。

:single-line-parameter-list: （无值）¶: 确保函数的参数将在单个逻辑行上发出，覆盖 c_maximum_signature_line_length 和 maximum_signature_line_length。

在 7.1 版本中添加。

.. c:macro:: name¶

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

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

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

在 3.0 版本中添加: 函数样式变体。

:single-line-parameter-list: （无值）¶: 确保宏的参数将在单个逻辑行上发出，覆盖 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。这些名称也可以在交叉引用中使用，即使省略嵌套符号也会被找到。@... 名称将始终呈现为 [匿名]（可能作为链接）。

示例

.. 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 [匿名]¶

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 域的选项。