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)

请注意，您不必反斜杠转义签名中的星号，因为它不会被其余的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枚举。

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支持匿名结构、枚举和联合。为了便于记录，必须给它们起一个以 @, e.g., @42 or @data. These names can also be used in cross-references, though nested symbols will be found even when omitted. The @... 名称将始终呈现为 [[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 重置堆栈并更改给定范围。

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

Sphinx

On this page

Site navigation

C域¶