Die C++-Domäne

Hinzugefügt in Version 1.0.

Die C++-Domäne (Name **cpp**) unterstützt die Dokumentation von C++-Projekten.

Direktiven zum Deklarieren von Entitäten

Die folgenden Direktiven sind verfügbar. Alle Deklarationen können mit einer Sichtbarkeitsanweisung beginnen (public, private oder protected).

.. cpp:class:: Klassen-Spezifizierer
.. cpp:struct:: Klassen-Spezifizierer

Beschreibt eine Klasse/Struktur, möglicherweise mit Angabe der Vererbung, z. B.

.. cpp:class:: MyClass : public MyBase, MyOtherBase

Der Unterschied zwischen cpp:class und cpp:struct ist rein kosmetisch: der Präfix, der in der Ausgabe gerendert wird, und der Spezifizierer, der im Index angezeigt wird.

Die Klasse kann direkt innerhalb eines verschachtelten Bereichs deklariert werden, z. B.

.. cpp:class:: OuterScope::MyClass : public MyBase, MyOtherBase

Eine Klassenvorlage kann deklariert werden

.. cpp:class:: template<typename T, std::size_t N> std::array

oder mit Zeilenumbruch

.. cpp:class:: template<typename T, std::size_t N> \
               std::array

Vollständige und partielle Template-Spezialisierungen können deklariert werden

.. cpp:class:: template<> \
               std::array<bool, 256>

.. cpp:class:: template<typename T> \
               std::array<T, 42>

Hinzugefügt in Version 2.0: Die cpp:struct-Direktive.

.. cpp:function:: (Member-)Funktions-Prototyp

Beschreibt eine Funktion oder Memberfunktion, z. B.

.. cpp:function:: bool myMethod(int arg1, std::string arg2)

   A function with parameters and types.

.. cpp:function:: bool myMethod(int, double)

   A function with unnamed parameters.

.. cpp:function:: const T &MyClass::operator[](std::size_t i) const

   An overload for the indexing operator.

.. cpp:function:: operator bool() const

   A casting operator.

.. cpp:function:: constexpr void foo(std::string &bar[2]) noexcept

   A constexpr function.

.. cpp:function:: MyClass::MyClass(const MyClass&) = default

   A copy constructor with default implementation.

Funktionsvorlagen können ebenfalls beschrieben werden

.. cpp:function:: template<typename U> \
                  void print(U &&u)

und Funktionsvorlagen-Spezialisierungen

.. cpp:function:: template<> \
                  void print(int i)
:single-line-parameter-list: (kein Wert)

Stellt sicher, dass die Parameter der Funktion auf einer einzigen logischen Zeile ausgegeben werden, wodurch cpp_maximum_signature_line_length und maximum_signature_line_length überschrieben werden.

Hinzugefügt in Version 7.1.

.. cpp:member:: (Member-)Variablendeklaration
.. cpp:var:: (Member-)Variablendeklaration

Beschreibt eine Variable oder Membervariable, z. B.

.. cpp:member:: std::string MyClass::myMember

.. cpp:var:: std::string MyClass::myOtherMember[N][M]

.. cpp:member:: int a = 42

Variablentemplates können ebenfalls beschrieben werden

.. cpp:member:: template<class T> \
                constexpr T pi = T(3.1415926535897932385)
.. cpp:type:: typedef-Deklaration
.. cpp:type:: Typname
.. cpp:type:: Typalias-Deklaration

Beschreibt einen Typ wie in einer typedef-Deklaration, einer Typalias-Deklaration oder einfach den Namen eines Typs mit nicht spezifiziertem Typ, z. B.

.. cpp:type:: std::vector<int> MyList

   A typedef-like declaration of a type.

.. cpp:type:: MyContainer::const_iterator

   Declaration of a type alias with unspecified type.

.. cpp:type:: MyType = std::unordered_map<int, std::string>

   Declaration of a type alias.

Ein Typalias kann auch templated sein

.. cpp:type:: template<typename T> \
              MyContainer = std::vector<T>

Die Beispiele werden wie folgt gerendert.

typedef std::vector<int> MyList

Eine typedef-ähnliche Deklaration eines Typs.

type MyContainer::const_iterator

Deklaration eines Typalias mit nicht spezifiziertem Typ.

using MyType = std::unordered_map<int, std::string>

Deklaration eines Typalias.

template<typename T>
using MyContainer = std::vector<T>
.. cpp:enum:: nicht-verschachtelte Enum-Deklaration
.. cpp:enum-struct:: verschachtelte Enum-Deklaration
.. cpp:enum-class:: verschachtelte Enum-Deklaration

Beschreibt ein (verschachteltes) Enum, möglicherweise mit Angabe des zugrundeliegenden Typs. Alle innerhalb eines nicht-verschachtelten Enums deklarierten Enumeratoren werden sowohl im Enum-Scope als auch im übergeordneten Scope deklariert. Beispiele

.. cpp:enum:: MyEnum

   An unscoped enum.

.. cpp:enum:: MySpecificEnum : long

   An unscoped enum with specified underlying type.

.. cpp:enum-class:: MyScopedEnum

   A scoped enum.

.. cpp:enum-struct:: protected MyScopedVisibilityEnum : std::underlying_type<MySpecificEnum>::type

   A scoped enum with non-default visibility, and with a specified
   underlying type.
.. cpp:enumerator:: Name
.. cpp:enumerator:: Name = Konstante

Beschreibt einen Enumerator, optional mit seinem definierten Wert, z. B.

.. cpp:enumerator:: MyEnum::myEnumerator

.. cpp:enumerator:: MyEnum::myOtherEnumerator = 42
.. cpp:union:: Name

Beschreibt eine Union.

Hinzugefügt in Version 1.8.

.. cpp:concept:: Template-Parameterliste Name

Warnung

Die Unterstützung für Konzepte ist experimentell. Sie basiert auf dem aktuellen Entwurf des Standards und der Concepts Technical Specification. Die Features können sich mit ihrer Entwicklung ändern.

Beschreibt ein Konzept. Es muss genau eine Template-Parameterliste haben. Der Name kann ein verschachtelter Name sein. Beispiel

.. cpp:concept:: template<typename It> std::Iterator

   Proxy to an element of a notional sequence that can be compared,
   indirected, or incremented.

   **Notation**

   .. cpp:var:: It r

      An lvalue.

   **Valid Expressions**

   - :cpp:expr:`*r`, when :cpp:expr:`r` is dereferenceable.
   - :cpp:expr:`++r`, with return type :cpp:expr:`It&`, when
     :cpp:expr:`r` is incrementable.

Dies wird wie folgt gerendert

template<typename It>
concept std::Iterator

Proxy zu einem Element einer nicht-expliziten Sequenz, das verglichen, indirekt aufgerufen oder inkrementiert werden kann.

Notation

It r

Ein Lvalue.

Gültige Ausdrücke

  • *r, wenn r dereferenzierbar ist.

  • ++r, mit Rückgabetyp It&, wenn r inkrementierbar ist.

Hinzugefügt in Version 1.5.

Optionen

Einige Direktiven unterstützen Optionen

  • :no-index-entry: und :no-contents-entry:, siehe Basis-Markup.

  • :tparam-line-spec:, für templated Deklarationen. Wenn angegeben, wird jeder Template-Parameter auf einer separaten Zeile gerendert.

    Hinzugefügt in Version 1.6.

Anonyme Entitäten

C++ unterstützt anonyme Namespaces, Klassen, Enums 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 und (Typ-)Ausdrücken verwendet werden, obwohl verschachtelte Symbole auch dann gefunden werden, wenn sie weggelassen werden. Der Name @... wird immer als **[anonym]** gerendert (möglicherweise als Link).

Beispiel

.. cpp:class:: Data

   .. cpp:union:: @data

      .. cpp:var:: int a

      .. cpp:var:: double b

Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`.

Dies wird wie folgt gerendert

class Data
union [anonymous]
int a
double b

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

Hinzugefügt in Version 1.8.

Alias-Deklarationen

Manchmal kann es hilfreich sein, Deklarationen außerhalb ihrer Hauptdokumentation aufzulisten, z. B. beim Erstellen einer Übersicht über eine Klassenschnittstelle. Die folgende Direktive kann zu diesem Zweck verwendet werden.

.. cpp:alias:: Name oder Funktionssignatur

Fügt eine oder mehrere Alias-Deklarationen ein. Jede Entität kann so spezifiziert werden, wie sie in der cpp:any-Rolle angegeben werden kann. Wenn der Name einer Funktion angegeben wird (im Gegensatz zur vollständigen Signatur), werden alle Überladungen der Funktion aufgelistet.

Zum Beispiel

.. cpp:alias:: Data::a
               overload_example::C::f

wird zu

int a
void f(double d) const
void f(double d)
void f(int i)
void f()

während

.. cpp:alias:: void overload_example::C::f(double d) const
               void overload_example::C::f(double d)

wird zu

void f(double d) const
void f(double d)

Hinzugefügt in Version 2.0.

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 genannte Deklaration. Standard ist 1.

Hinzugefügt in Version 3.5.

:noroot:

Überspringt die genannten Deklarationen und rendert nur verschachtelte Deklarationen. Erfordert maxdepth entweder 0 oder mindestens 2.

Hinzugefügt in Version 3.5.

Eingeschränkte Templates

Warnung

Die Unterstützung für Konzepte ist experimentell. Sie basiert auf dem aktuellen Entwurf des Standards und der Concepts Technical Specification. Die Features können sich mit ihrer Entwicklung ändern.

Hinweis

Sphinx unterstützt derzeit keine requires-Klauseln.

Platzhalter

Deklarationen können den Namen eines Konzepts verwenden, um eingeschränkte Template-Parameter einzuführen, oder das Schlüsselwort auto, um unbeschränkte Template-Parameter einzuführen

.. cpp:function:: void f(auto &&arg)

   A function template with a single unconstrained template parameter.

.. cpp:function:: void f(std::Iterator it)

   A function template with a single template parameter, constrained by the
   Iterator concept.

Template-Einführungen

Einfache eingeschränkte Funktions- oder Klassentemplates können mit einer Template-Einführung anstelle einer Template-Parameterliste deklariert werden

.. cpp:function:: std::Iterator{It} void advance(It &it)

    A function template with a template parameter constrained to be an
    Iterator.

.. cpp:class:: std::LessThanComparable{T} MySortedContainer

    A class template with a template parameter constrained to be
    LessThanComparable.

Sie werden wie folgt gerendert.

std::Iterator{It}
void advance(It &it)

Eine Funktionsvorlage mit einem Template-Parameter, der auf Iterator eingeschränkt ist.

std::LessThanComparable{T}
class MySortedContainer

Eine Klassenvorlage mit einem Template-Parameter, der auf LessThanComparable eingeschränkt ist.

Beachten Sie jedoch, dass keine Überprüfung auf Parameterkompatibilität durchgeführt wird. Z. B. wird Iterator{A, B, C} als Einführung akzeptiert, obwohl es kein gültiges C++ wäre.

Inline-Ausdrücke und Typen

:cpp:expr:
:cpp:texpr:

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

.. cpp:var:: int a = 42

.. cpp:function:: int f(int i)

An expression: :cpp:expr:`a * f(a)` (or as text: :cpp:texpr:`a * f(a)`).

A type: :cpp:expr:`const MySortedContainer<int>&`
(or as text :cpp:texpr:`const MySortedContainer<int>&`).

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 MySortedContainer<int>& (oder als Text const MySortedContainer<int>&).

Hinzugefügt in Version 1.7: Die cpp:expr-Rolle.

Hinzugefügt in Version 1.8: Die cpp:texpr-Rolle.

Namespacing

Deklarationen in der C++-Domäne werden standardmäßig im globalen Scope platziert. Der aktuelle Scope kann mit drei Namespace-Direktiven geändert werden. Sie verwalten einen Stapel von Deklarationen, wobei cpp:namespace den Stapel zurücksetzt und einen angegebenen Scope ändert.

Die Direktive cpp:namespace-push ändert den Scope relativ zum aktuellen Scope.

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

.. cpp:namespace:: Scope-Spezifikation

Ändert den aktuellen Scope für nachfolgende Objekte auf den angegebenen Scope und setzt den Stapel der Namespace-Direktiven zurück. Beachten Sie, dass der Namespace nicht mit C++-Namespaces übereinstimmen muss, sondern in Klassennamen enden kann, z. B.

.. cpp:namespace:: Namespace1::Namespace2::SomeClass::AnInnerClass

Alle nachfolgenden Objekte werden so definiert, als ob ihr Name mit dem Scope vorangestellt deklariert worden wäre. Die nachfolgenden Querverweise werden beginnend im aktuellen Scope gesucht.

Die Verwendung von NULL, 0 oder nullptr als Scope wechselt zum globalen Scope.

Eine Namespace-Deklaration kann auch templated sein, z. B.

.. cpp:class:: template<typename T> \
               std::vector

.. cpp:namespace:: template<typename T> std::vector

.. cpp:function:: std::size_t size() const

deklariert size als Memberfunktion der Klassenvorlage std::vector. Äquivalent hätte dies deklariert werden können mit

.. cpp:class:: template<typename T> \
               std::vector

   .. cpp:function:: std::size_t size() const

oder

.. cpp:class:: template<typename T> \
               std::vector
.. cpp:namespace-push:: Scope-Spezifikation

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

.. cpp:namespace:: A::B

.. cpp:namespace-push:: C::D

wird der aktuelle Scope A::B::C::D sein.

Hinzugefügt in Version 1.4.

.. cpp:namespace-pop::

Macht die vorherige cpp:namespace-push-Direktive rückgängig (nicht nur einen Scope entfernen). Zum Beispiel, nach

.. cpp:namespace:: A::B

.. cpp:namespace-push:: C::D

.. cpp:namespace-pop::

wird der aktuelle Scope A::B sein (nicht A::B::C).

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

.. cpp:namespace:: nullptr

.. cpp:namespace-push:: A::B

Hinzugefügt in Version 1.4.

Info-Feldlisten

Alle C++-Direktiven zum Deklarieren von Entitäten unterstützen die folgenden Info-Felder (siehe auch Info-Feldlisten)

  • tparam: Beschreibung eines Template-Parameters.

Die Direktive cpp:function unterstützt zusätzlich die folgenden Felder

  • param, parameter, arg, argument: Beschreibung eines Parameters.

  • returns, return: Beschreibung eines Rückgabewerts.

  • retval, retvals: Eine Alternative zu returns zur Beschreibung des Ergebnisses der Funktion.

  • throws, throw, exception: Beschreibung einer möglicherweise ausgelösten Ausnahme.

Hinzugefügt in Version 4.3: Der Feldtyp retval.

Querverweise

Diese Rollen verknüpfen mit den gegebenen Deklarationstypen

:cpp:any:
:cpp:class:
:cpp:struct:
:cpp:func:
:cpp:member:
:cpp:var:
:cpp:type:
:cpp:concept:
:cpp:enum:
:cpp:enumerator:

Verweist auf eine C++-Deklaration anhand ihres Namens (weitere Details siehe unten). Der Name muss relativ zur Position des Links korrekt qualifiziert sein.

Hinzugefügt in Version 2.0: Die Rolle :cpp:struct: als Alias für die Rolle :cpp:class:.

Hinweis zu Verweisen mit Template-Parametern/Argumenten

Diese Rollen folgen den Syntaxregeln von Sphinx. Das bedeutet, dass bei der Referenzierung einer (partiellen) Template-Spezialisierung Vorsicht geboten ist. Wenn der Link beispielsweise so aussieht: :cpp:class:`MyClass<int>`. Dies wird als Link zu int mit dem Titel MyClass interpretiert. In diesem Fall escapen Sie die öffnende spitze Klammer mit einem Backslash, wie folgt: :cpp:class:`MyClass\<int>`.

Wenn kein benutzerdefinierter Titel benötigt wird, kann es nützlich sein, die Rollen für Inline-Ausdrücke :cpp:expr: und :cpp:texpr: zu verwenden, bei denen spitze Klammern nicht escapet werden müssen.

Deklarationen ohne Template-Parameter und Template-Argumente

Für die Verlinkung zu nicht-temperierten Deklarationen muss der Name ein verschachtelter Name sein, z. B. f oder MyClass::f.

Überladene (Member-)Funktionen

Wenn eine (Member-)Funktion nur über ihren Namen referenziert wird, verweist der Verweis auf eine beliebige passende Überladung. Die Rollen :cpp:any: und :cpp:func: verwenden ein alternatives Format, das einfach eine vollständige Funktionsdeklaration ist. Dies löst die exakt passende Überladung auf. Als Beispiel betrachten wir die folgende Klassen-Deklaration

class C
void f(double d) const
void f(double d)
void f(int i)
void f()

Verweise mit der Rolle :cpp:func:

Beachten Sie, dass die Konfigurationsvariable add_function_parentheses spezifische Überladungsreferenzen nicht beeinflusst.

Templetisierte Deklarationen

Angenommen, die folgenden Deklarationen.

class Wrapper
template<typename TOuter>
class Outer
template<typename TInner>
class Inner

Im Allgemeinen muss der Verweis die Template-Parameter-Deklarationen und Template-Argumente für den Präfix von qualifizierten Namen enthalten. Zum Beispiel

  • template\<typename TOuter> Wrapper::Outer (template<typename TOuter> Wrapper::Outer)

  • template\<typename TOuter> template\<typename TInner> Wrapper::Outer<TOuter>::Inner (template<typename TOuter> template<typename TInner> Wrapper::Outer<TOuter>::Inner)

Derzeit gelingt die Suche nur, wenn die Bezeichner der Template-Parameter identische Zeichenketten sind. Das heißt, template\<typename UOuter> Wrapper::Outer funktioniert nicht.

Als Kurzschreibweise gilt: Wenn eine Template-Parameterliste weggelassen wird, geht die Suche von einer primären Template- oder einer Nicht-Template-Deklaration aus, nicht jedoch von einer partiellen Template-Spezialisierung. Das bedeutet, dass die folgenden Verweise ebenfalls funktionieren

(Vollständige) Template-Spezialisierungen

Angenommen, die folgenden Deklarationen.

template<typename TOuter>
class Outer
template<typename TInner>
class Inner
template<>
class Outer<int>
template<typename TInner>
class Inner
template<>
class Inner<bool>

Im Allgemeinen muss der Verweis eine Template-Parameterliste für jede Template-Argumentenliste enthalten. Die obige vollständige Spezialisierung kann daher mit template\<> Outer\<int> (template<> Outer<int>) und template\<> template\<> Outer\<int>::Inner\<bool> (template<> template<> Outer<int>::Inner<bool>) referenziert werden. Als Kurzschreibweise kann die leere Template-Parameterliste weggelassen werden, z. B. Outer\<int> (Outer<int>) und Outer\<int>::Inner\<bool> (Outer<int>::Inner<bool>).

Partielle Template-Spezialisierungen

Angenommen, die folgende Deklaration.

template<typename T>
class Outer<T*>

Referenzen auf partielle Spezialisierungen müssen immer die Template-Parameterlisten enthalten, z. B. template\<typename T> Outer\<T*> (template<typename T> Outer<T*>). Derzeit gelingt die Suche nur, wenn die Bezeichner der Template-Parameter identische Zeichenketten sind.

Konfigurationsvariablen

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