Die C-Domäne¶

Hinzugefügt in Version 1.0.

Die C-Domäne (Name **c**) eignet sich für die Dokumentation von C-APIs.

.. c:member:: declaration¶

.. c:var:: declaration¶

Beschreibt ein C-Strukturmitglied oder eine Variable. Beispiel-Signatur

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

Der Unterschied zwischen den beiden Direktiven ist nur kosmetisch.

.. c:function:: function prototype¶

Beschreibt eine C-Funktion. Die Signatur sollte wie in C angegeben werden, z. B.

.. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)

Beachten Sie, dass Sie Sternchen (*) in der Signatur nicht mit einem Backslash maskieren müssen, da sie nicht vom reStructuredText-Inliner analysiert werden.

In der Beschreibung einer Funktion können Sie die folgenden Info-Felder verwenden (siehe auch Info-Feldlisten).

param, parameter, arg, argument: Beschreibung eines Parameters.
type: Typ eines Parameters, geschrieben, als ob er an die c:expr-Rolle übergeben würde.
returns, return: Beschreibung des Rückgabewerts.
rtype: Rückgabetyp, geschrieben, als ob er an die c:expr-Rolle übergeben würde.
retval, retvals: Eine Alternative zu returns zur Beschreibung des Ergebnisses der Funktion.

Hinzugefügt in Version 4.3: Der Feldtyp retval.

Zum Beispiel

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

was gerendert wird als

PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)¶

Kein Inhaltsverzeichniseintrag:

Kein Indexeintrag:

Parameter:

type – Beschreibung des ersten Parameters.
nitems – Beschreibung des zweiten Parameters.

Gibt zurück:

ein Ergebnis.

Rückgabewerte:

NULL – unter bestimmten Bedingungen.
NULL – auch unter einigen anderen Bedingungen.

:single-line-parameter-list: (kein Wert)¶: Stellt sicher, dass die Parameter der Funktion auf einer einzigen logischen Zeile ausgegeben werden, wodurch c_maximum_signature_line_length und maximum_signature_line_length überschrieben werden.

Hinzugefügt in Version 7.1.

.. c:macro:: name¶

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

Beschreibt ein C-Makro, d. h. ein C-Sprach-#define, ohne den Ersatztext.

In der Beschreibung eines Makros können Sie dieselben Info-Felder wie für die Direktive c:function verwenden.

Hinzugefügt in Version 3.0: Die Funktionsstil-Variante.

:single-line-parameter-list: (kein Wert)¶: Stellt sicher, dass die Parameter des Makros auf einer einzigen logischen Zeile ausgegeben werden, wodurch c_maximum_signature_line_length und maximum_signature_line_length überschrieben werden.

Hinzugefügt in Version 7.1.

.. c:struct:: name¶: Beschreibt eine C-Struktur.

Hinzugefügt in Version 3.0.

.. c:union:: name¶: Beschreibt eine C-Union.

Hinzugefügt in Version 3.0.

.. c:enum:: name¶: Beschreibt eine C-Aufzählung (enum).

Hinzugefügt in Version 3.0.

.. c:enumerator:: name¶: Beschreibt einen C-Aufzählungswert (enumerator).

Hinzugefügt in Version 3.0.

.. c:type:: typedef-like declaration¶
.. c:type:: name: Beschreibt einen C-Typ, entweder als Typedef oder als Alias für einen nicht spezifizierten Typ.

Cross-Referenzierung von C-Konstrukten¶

Die folgenden Rollen erzeugen Querverweise auf C-Sprachkonstrukte, wenn diese in der Dokumentation definiert sind.

:c:member:¶
:c:data:¶
:c:var:¶
:c:func:¶
:c:macro:¶
:c:struct:¶
:c:union:¶
:c:enum:¶
:c:enumerator:¶
:c:type:¶: Referenziert eine C-Deklaration, wie oben definiert. Beachten Sie, dass c:member, c:data und c:var äquivalent sind.

Hinzugefügt in Version 3.0: Die Rollen var, struct, union, enum und enumerator.

Anonyme Entitäten¶

C unterstützt anonyme Strukturen, Aufzählungen und Unions. Zu Dokumentationszwecken müssen ihnen Namen gegeben werden, die mit @ beginnen, z. B. @42 oder @data. Diese Namen können auch in Querverweisen verwendet werden, obwohl verschachtelte Symbole auch dann gefunden werden, wenn sie weggelassen werden. Der Name @... wird immer als **[anonymous]** gerendert (möglicherweise als Link).

Beispiel

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

Dies wird gerendert als

struct Data¶

union [anonymous]¶

int a¶

double b¶

Expliziter Verweis: Data.[anonymous].a. Kurzer Verweis: Data.a.

Hinzugefügt in Version 3.0.

Aliasing-Deklarationen¶

Manchmal kann es hilfreich sein, Deklarationen an anderer Stelle als ihrer Hauptdokumentation aufzulisten, z. B. beim Erstellen einer Synopsis einer Schnittstelle. Die folgende Direktive kann für diesen Zweck verwendet werden.

.. c:alias:: name¶

Fügt eine oder mehrere Alias-Deklarationen ein. Jede Entität kann so angegeben werden, wie sie in der Rolle c:any angegeben werden kann.

Zum Beispiel

.. c:var:: int data
.. c:function:: int f(double k)

.. c:alias:: data
             f

wird zu

int data¶

int f(double k)¶

int data
int f(double k)

Hinzugefügt in Version 3.2.

Optionen

:maxdepth: int¶: Fügt auch verschachtelte Deklarationen ein, bis zur angegebenen Gesamttiefe. Verwenden Sie 0 für unendliche Tiefe und 1 nur für die erwähnte Deklaration. Standardwert ist 1.

Hinzugefügt in Version 3.3.

:noroot:¶: Überspringt die erwähnten Deklarationen und rendert nur verschachtelte Deklarationen. Erfordert maxdepth entweder 0 oder mindestens 2.

Hinzugefügt in Version 3.5.

Inline-Ausdrücke und -Typen¶

:c:expr:¶

:c:texpr:¶

Fügt einen C-Ausdruck oder -Typ entweder als Inline-Code (cpp:expr) oder als Inline-Text (cpp:texpr) ein. Zum Beispiel

.. 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*`).

wird wie folgt gerendert

int a = 42¶

int f(int i)¶

Ein Ausdruck: a * f(a) (oder als Text: a * f(a)).

Ein Typ: const Data* (oder als Text const Data*).

Hinzugefügt in Version 3.0.

Namensräume¶

Hinzugefügt in Version 3.1.

Die C-Sprache selbst unterstützt keine Namensräume, aber es kann manchmal nützlich sein, sie in der Dokumentation zu emulieren, z. B. um alternative Deklarationen anzuzeigen. Das Feature kann auch verwendet werden, um Mitglieder von Strukturen/Unions/Aufzählungen getrennt von ihrer übergeordneten Deklaration zu dokumentieren.

Der aktuelle Geltungsbereich kann mit drei Namespace-Direktiven geändert werden. Sie verwalten einen Stapel von Deklarationen, wobei c:namespace den Stapel zurücksetzt und einen bestimmten Geltungsbereich ändert.

Die Direktive c:namespace-push ändert den Geltungsbereich zu einem gegebenen inneren Geltungsbereich des aktuellen.

Die Direktive c:namespace-pop macht die letzte c:namespace-push-Direktive rückgängig.

.. c:namespace:: scope specification¶

Ändert den aktuellen Geltungsbereich für die nachfolgenden Objekte auf den angegebenen Geltungsbereich und setzt den Stapel der Namespace-Direktiven zurück. Beachten Sie, dass verschachtelte Geltungsbereiche durch Trennung mit einem Punkt angegeben werden können, z. B.

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

Alle nachfolgenden Objekte werden definiert, als ob ihr Name mit dem Geltungsbereich vorangestellt deklariert worden wäre. Die nachfolgenden Querverweise werden ab dem aktuellen Geltungsbereich durchsucht.

Die Verwendung von NULL oder 0 als Geltungsbereich wechselt zum globalen Geltungsbereich.

.. c:namespace-push:: scope specification¶

Ändert den Geltungsbereich relativ zum aktuellen Geltungsbereich. Zum Beispiel, nach

.. c:namespace:: A.B

.. c:namespace-push:: C.D

wird der aktuelle Geltungsbereich A.B.C.D sein.

.. c:namespace-pop::¶

Macht die vorherige c:namespace-push-Direktive rückgängig (nicht nur einen Geltungsbereich aus dem Stapel nehmen). Zum Beispiel, nach

.. c:namespace:: A.B

.. c:namespace-push:: C.D

.. c:namespace-pop::

wird der aktuelle Geltungsbereich A.B sein (nicht A.B.C).

Wenn keine vorherige c:namespace-push-Direktive verwendet wurde, sondern nur eine c:namespace-Direktive, dann wird der aktuelle Geltungsbereich auf den globalen Geltungsbereich zurückgesetzt. Das heißt, .. c:namespace:: A.B ist äquivalent zu

.. c:namespace:: NULL

.. c:namespace-push:: A.B

Konfigurationsvariablen¶

Siehe Optionen für die C-Domäne.