C 領域¶

版本 1.0 新增。

C 領域（名稱為 c）適用於 C API 的文件。

.. c:member:: 宣告¶

.. c:var:: 宣告¶

描述 C 結構的成員或變數。範例簽名

.. c:member:: PyObject *PyTypeObject.tp_bases

這兩個指令之間的差異僅在於外觀。

.. c:function:: 函式原型¶

描述 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: （無值）¶: 確保函式的參數將在單一邏輯行上發出，覆寫 c_maximum_signature_line_length 和 maximum_signature_line_length。

版本 7.1 新增。

.. c:macro:: 名稱¶

.. c:macro:: 名稱(參數列表)

描述 C 巨集，即 C 語言的 #define，不包含替換文字。

在巨集的描述中，您可以使用與 c:function 指令相同的資訊欄位。

版本 3.0 新增：函式樣式變體。

:single-line-parameter-list: （無值）¶: 確保巨集的參數將在單一邏輯行上發出，覆寫 c_maximum_signature_line_length 和 maximum_signature_line_length。

版本 7.1 新增。

.. c:struct:: 名稱¶: 描述 C 結構。

版本 3.0 新增。

.. c:union:: 名稱¶: 描述 C 聯合。

版本 3.0 新增。

.. c:enum:: 名稱¶: 描述 C 列舉。

版本 3.0 新增。

.. c:enumerator:: 名稱¶: 描述 C 列舉值。

版本 3.0 新增。

.. c:type:: typedef-like 宣告¶
.. c:type:: 名稱: 描述 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 是等效的。

版本 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:`[email protected]`. Short-hand ref: :c:var:`Data.a`.

這將呈現為

struct Data¶

union [anonymous]¶

int a¶

double b¶

顯式參照：Data.[anonymous].a。簡寫參照：Data.a。

版本 3.0 新增。

別名宣告¶

有時，在主要文件以外的地方列出宣告可能會很有幫助，例如，在建立介面概要時。以下指令可用於此目的。

.. c:alias:: 名稱¶

插入一個或多個別名宣告。每個實體都可以像在 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 表示僅提及的宣告。預設值為 1。

版本 3.3 新增。

:noroot:¶: 跳過提及的宣告，僅呈現巢狀宣告。需要 maxdepth 為 0 或至少為 2。

版本 3.5 新增。

行內表達式與類型¶

:c:expr:¶

:c:texpr:¶

以行內程式碼 (cpp:expr) 或行內文字 (cpp:texpr) 插入 C 表達式或類型。例如

.. 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 重置堆疊並變更給定的作用域。

c:namespace-push 指令將作用域變更為目前作用域的給定內部作用域。

c:namespace-pop 指令會撤銷最近的 c:namespace-push 指令。

.. c:namespace:: 作用域規範¶

將後續物件的目前作用域變更為給定的作用域，並重置命名空間指令堆疊。請注意，巢狀作用域可以使用點分隔來指定，例如：

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

所有後續物件都將被定義為其名稱以作用域作為前綴宣告。後續的交叉參照將從目前作用域開始搜尋。

使用 NULL 或 0 作為作用域將變更為全域作用域。

.. c:namespace-push:: 作用域規範¶

相對於目前作用域變更作用域。例如，在

.. 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 領域的選項。