c结构域¶

Added in version 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 inliner不会解析它。

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

param , parameter , arg , argument ，参数的描述。
type ：参数的类型，写得就像传递给 c:expr 作用
returns , return ：返回值的描述。
rtype ：返回类型，写得就像传递给 c:expr 作用
retval , retvals ：替代品 returns 用于描述函数的结果。

Added in version 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 .

Added in version 7.1.

.. c:macro:: name¶

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

描述C宏，即C语言 #define ，没有替换文本。

在宏的描述中，您可以使用与 c:function 指令。

Added in version 3.0: 功能风格变体。

:single-line-parameter-list: (no value)¶: 确保宏的参数将在单个逻辑行上发出，重写 c_maximum_signature_line_length 和 maximum_signature_line_length .

Added in version 7.1.

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

Added in version 3.0.

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

Added in version 3.0.

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

Added in version 3.0.

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

Added in version 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 是等价的。

Added in version 3.0: var、struct、union、enum和enumator角色。

匿名实体¶

C支持匿名结构、列举和联合。为了记录起见，必须给它们起一些以 @, e.g., @42 or @data. These names can also be used in cross-references, though nested symbols will be found even when omitted. The @... name将始终呈现为 [anonymous] （可能作为链接）。

示例：：

.. c:struct:: Data

   .. c:union:: @data

      .. c:var:: int a

      .. c:var:: double b

Explicit ref: :c:var:`Data.@data.a`. Short-hand ref: :c:var:`Data.a`.

这将呈现为：

struct Data¶

union [anonymous]¶

int a¶

double b¶

明确参考： Data.[anonymous].a .空头裁判： Data.a .

Added in version 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)

Added in version 3.2.

选项

:maxdepth: int¶: 也插入嵌套声明，最多插入给定的总深度。使用0表示无限深度，使用1表示提到的声明。返回至1。

Added in version 3.3.

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

Added in version 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) (or文本： a * f(a) ).

A类型： const Data* (or诸如文字 const Data* ).

Added in version 3.0.

命名空间¶

Added in version 3.1.

C语言本身不支持命名空间，但有时在文档中模拟它会很有用，例如，以显示替代声明。该功能还可用于记录结构/联合/enum的成员，与其父声明分开。

可以使用三个命名空间指令更改当前范围。它们管理堆栈声明，其中 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 指令（ not 只需弹出一个范围）。例如，在：：之后

.. c:namespace:: A.B

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

.. c:namespace-pop::

当前的范围将是 A.B ( not A.B.C ).

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

.. c:namespace:: NULL

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

配置变量¶

看到针对C域的选项 .