C ドメイン¶

バージョン 1.0 で追加。

C ドメイン (名前は c) は C API のドキュメントに適しています。

.. c:member:: 宣言¶

.. c:var:: 宣言¶

C 構造体のメンバーまたは変数を記述します。署名の例

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

2 つのディレクティブの違いは、見た目だけです。

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

コンテンツエントリなし:

インデックスエントリなし:

パラメーター:

type – 最初のパラメーターの説明。
nitems – 2 番目のパラメーターの説明。

戻り値:

結果。

戻り値:

NULL – 特定の条件下。
NULL – 他の条件でも。

:single-line-parameter-list: (値なし)¶: 関数のパラメーターが論理的な 1 行で出力されるようにします。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: (値なし)¶: マクロのパラメーターが論理的な 1 行で出力されるようにします。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 のような宣言¶
.. 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 は同等であることに注意してください。

バージョン 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。

バージョン 3.0 で追加。

エイリアス宣言¶

インターフェースの概要を作成する場合など、メインのドキュメント以外の場所に宣言をリストすると便利な場合があります。この目的には、次のディレクティブを使用できます。

.. c:alias:: name¶

1つ以上のエイリアス宣言を挿入します。各エンティティは、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:¶

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 で追加。

名前空間¶

バージョン 3.1 で追加。

C 言語自体は名前空間をサポートしていませんが、ドキュメントでそれをエミュレートすると便利な場合があります。たとえば、代替の宣言を示す場合です。この機能は、構造体/共用体/列挙体のメンバーを親の宣言とは別にドキュメント化するためにも使用できます。

現在のスコープは、3 つの名前空間ディレクティブを使用して変更できます。これらは、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 ドメインのオプションを参照してください。