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: (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 指令相同的信息字段。

在 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类型描述为类型定义或未指定类型的别名。

交叉引用C构造¶

如果在文档中定义了以下角色，则会创建对C语言构造的交叉引用::c:func:

: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、枚举和枚举器角色。

匿名的实体¶

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¶

显式 ref: Data.[anonymous].a 。简写 ref: 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表示 mentioned declaration 。默认为1。

在 3.3 版本加入.

:noroot:¶: 跳过 mentioned declarations ，只渲染嵌套的声明。要求 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”重置堆栈并更改给定的范围。

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

cpp:namespace-pop 指令撤消了最新的 cpp:namespace-push 指令。

.. c:namespace:: scope specification¶

将后续对象的当前范围更改为给定范围，并重置命名空间指令堆栈。请注意，命名空间不需要与C++ 命名空间相对应，但可以以类的名称结尾，例如:

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

将定义所有后续对象，就好像它们的名称是在前置范围的情况下声明的一样。将在当前范围中搜索后续交叉引用。

使用 NULL， 0 或 nullptr 作为范围将变为全局范围。

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