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)

请注意，签名中不必使用反斜杠转义星号，因为reST内联器不会对其进行解析。

In the description of a function you can use the following info fields (see also 信息字段列表).

param, parameter, arg, argument, Description of a parameter.
type: Type of a parameter, written as if passed to the c:expr role.
“returns”，“return”：返回值的描述。
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:

No-index-entry:

参数:

type – description of the first parameter.
nitems – description of the second parameter.

返回:

a result.

返回值:

NULL – under some conditions.
NULL – under some other conditions as well.

:single-line-parameter-list: (no value)¶: Ensures that the function’s parameters will be emitted on a single logical line, overriding c_maximum_signature_line_length and maximum_signature_line_length.

Added in version 7.1.

.. c:macro:: name¶

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

描述一个C宏，即，C语言的“#define”，不包含替换文本。

In the description of a macro you can use the same info fields as for the c:function directive.

Added in version 3.0: 函数样式的变体。

:single-line-parameter-list: (no value)¶: Ensures that the macro’s parameters will be emitted on a single logical line, overriding c_maximum_signature_line_length and 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类型描述为类型定义或未指定类型的别名。

交叉引用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、 :rst:role:`c:data`和:rst:role:`c:var`是等价的。

Added in version 3.0: var、struct、union、枚举和枚举器角色。

匿名的实体¶

C++ 支持匿名命名空间、类、枚举和联合。为了文档起见，必须给它们一些以 “@ ”开头的名字，例如，“@42”或 “@data”。这些名称也可以在交叉引用中使用，尽管嵌套符号即使在省略时也会被找到。 “@…”名称将始终显示为**[匿名]**（可能作为链接）。

例如:

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

显式 ref: Data.[anonymous].a 。简写 ref: Data.a。

Added in version 3.0.

别名声明¶

有时，除了主要文档之外，它可能是有用的列表声明，例如，在创建类接口的概要时。以下指令可用于此目的。

.. c:alias:: name¶

插入一个或多个别名声明。可以在 :rst:role:`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表示 mentioned declaration 。默认为1。

Added in version 3.3.

:noroot:¶: 跳过 mentioned declarations ，只渲染嵌套的声明。要求 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)`（或文本: :c:texpr:`a * f(a)）。

类型: const Data*`（或作为文本 :c:texpr:`const Data*）。

Added in version 3.0.

命名空间¶

Added in version 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.”（不是“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域¶