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内联解析.

在函数的描述中,你可以使用以下信息字段（参见:ref:info-field-lists ）.

param, parameter, arg, argument, Description of a parameter.
type: Type of a parameter, written as if passed to the c:expr role.
returns, return: Description of the return value.
rtype: Return type, written as if passed to the c:expr role.
retval, retvals: An alternative to returns for describing the result of the function.

Added in version 4.3: The retval field type.

例如:

.. 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.

which renders as 减少为

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

No-contents-entry:

不索引条目:

参数:

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 枚举.

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 和 enumerator 的角色.

匿名实体¶

C 支持匿名结构体、枚举和联合体.出于文档目的,它们必须被赋予一些以 @ 开头的名称,例如 @42 或 @data .这些名称也可以用于交叉引用,尽管嵌套符号即使省略也会被找到. @... 的名称将始终被渲染为 [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) （或作为文本: a * f(a) ）.

类型: const Data* (或文本形式 const Data* ).

Added in version 3.0.

命名空间¶

Added in version 3.1.

C语言本身不支持命名空间,但在文档中模拟命名空间有时是有用的,例如,显示替代声明.该功能还可以用于单独记录结构体/联合体/枚举的成员,而与其父声明分开.

当前作用域可以使用三个命名空间指令进行更改.它们管理一个堆栈声明,其中 c:namespace 重置堆栈并更改给定的作用域.

The c:namespace-push directive changes the scope to a given inner scope of the current one.

The c:namespace-pop directive undoes the most recent c:namespace-push directive.

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