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)¶
- 无内容条目:
- 无索引条目:
- 参数:
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: (无值)¶
确保宏的参数将在一个逻辑行上输出，覆盖
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 类型，可以是 typedef，也可以是未指定类型的别名。
交叉引用 C 构造¶
如果 C 语言构造在文档中定义，以下角色将创建对其的交叉引用
匿名实体¶
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`.
这将渲染为
显式引用: Data.[anonymous].a. 简写引用: 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)¶
3.2 版本新增。
选项
- :maxdepth: int¶
也插入嵌套声明，直到给定的总深度。0 表示无限深度，1 表示只列出提到的声明。默认为 1。
在版本 3.3 中新增。
- :noroot:¶
跳过提到的声明，只渲染嵌套声明。要求
maxdepth为 0 或至少 2。版本 3.5 中新增。
-
int data¶
内联表达式和类型¶
- :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 版本新增。
-
int a = 42¶
命名空间¶
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指令（而不是仅仅弹出作用域）。例如，在.. 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 领域选项。