C++ドメイン

バージョン1.0で追加.

C++ドメイン(名前はcpp)は、C++プロジェクトのドキュメント化をサポートします。

エンティティを宣言するためのディレクティブ

以下のディレクティブが利用可能です。すべての宣言は、可視性ステートメント(public、private、またはprotected)で始めることができます。

.. cpp:class:: class specifier
.. cpp:struct:: class specifier

クラス/構造体を記述します。おそらく継承の仕様も記述します。例:

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

cpp:classとcpp:structの違いは、見た目上の違いだけです。出力にレンダリングされる接頭辞と、インデックスに表示される指定子です。

クラスは、ネストされたスコープ内で直接宣言できます。例:

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

クラステンプレートは宣言できます

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

または改行ありで

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

完全および部分的なテンプレート特殊化を宣言できます

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

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

バージョン 2.0 で追加: cpp:struct ディレクティブ。

.. cpp:function:: (member) function prototype

関数またはメンバー関数を記述します。例:

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

関数テンプレートも記述できます

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

また、関数テンプレートの特殊化も記述できます

.. cpp:function:: template<> \
                  void print(int i)
:single-line-parameter-list: (値なし)

関数のパラメーターが、cpp_maximum_signature_line_lengthとmaximum_signature_line_lengthをオーバーライドして、単一の論理行で出力されるようにします。

バージョン 7.1 で追加.

.. cpp:member:: (member) variable declaration
.. cpp:var:: (member) variable declaration

変数またはメンバー変数を記述します。例:

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

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

.. cpp:member:: int a = 42

変数テンプレートも記述できます

.. cpp:member:: template<class T> \
                constexpr T pi = T(3.1415926535897932385)
.. cpp:type:: typedef declaration
.. cpp:type:: name
.. cpp:type:: type alias declaration

typedef宣言、型エイリアス宣言、または単純に型を指定せずに型名を記述します。例:

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

型エイリアスもテンプレート化できます

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

例は次のようにレンダリングされます。

typedef std::vector<int> MyList

型のtypedefのような宣言。

type MyContainer::const_iterator

型が指定されていない型エイリアスの宣言。

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

型エイリアスの宣言。

template<typename T>
using MyContainer = std::vector<T>
.. cpp:enum:: unscoped enum declaration
.. cpp:enum-struct:: scoped enum declaration
.. cpp:enum-class:: scoped enum declaration

（スコープ付きの）enum を記述します。基になる型が指定されている場合もあります。スコープなし enum 内で宣言された列挙子は、enum スコープと親スコープの両方で宣言されます。例:

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

列挙子を記述します。必要に応じて値を定義できます。例:

.. cpp:enumerator:: MyEnum::myEnumerator

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

union を記述します。

バージョン 1.8 で追加。

.. cpp:concept:: template-parameter-list name

警告

concept のサポートは実験的です。現在のドラフト標準と Concepts Technical Specification に基づいています。機能は進化するにつれて変更される可能性があります。

concept を記述します。テンプレートパラメータリストはちょうど 1 つ必要です。名前はネストされた名前でも構いません。例:

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

これは次のようにレンダリングされます。

template<typename It>
concept std::Iterator

比較、間接参照、またはインクリメントできる概念的なシーケンスの要素へのプロキシ。

表記

It r

左辺値。

有効な式

  • *r。ただし、r が間接参照可能である場合。

  • ++r。戻り型は It&。ただし、r がインクリメント可能である場合。

バージョン 1.5 で追加。

オプション

一部のディレクティブはオプションをサポートしています

  • :no-index-entry: および :no-contents-entry:。 基本マークアップを参照してください。

  • :tparam-line-spec:。テンプレート化された宣言の場合。指定した場合、各テンプレートパラメータは別の行にレンダリングされます。

    バージョン 1.6 で追加。

匿名エンティティ

C++ は匿名名前空間、クラス、enum、union をサポートしています。ドキュメントの目的のため、それらには @ で始まる名前（例: @42 や @data）を付ける必要があります。これらの名前は相互参照や（型）式でも使用できますが、ネストされたシンボルは省略した場合でも見つかります。@... という名前は常に [anonymous] としてレンダリングされます（リンクの場合もあります）。

例

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

これは次のようにレンダリングされます。

class Data
union [anonymous]
int a
double b

明示的な参照: Data::[anonymous]::a。省略形参照: Data::a。

バージョン 1.8 で追加。

エイリアス宣言

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

.. cpp:alias:: name or function signature

1 つ以上のエイリアス宣言を挿入します。各エンティティは、cpp:any ロールで可能なように指定できます。関数の名前（完全なシグネチャではなく）が指定された場合、その関数のすべてのオーバーロードがリストされます。

たとえば

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

は次のようになります。

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

一方

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

は次のようになります。

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

バージョン 2.0 で追加。

オプション

:maxdepth: int

ネストされた宣言も、指定された合計の深さまで挿入します。無限の深さには 0 を、記述した宣言のみには 1 を使用します。デフォルトは 1 です。

バージョン 3.5 で追加。

:noroot:

記述した宣言をスキップし、ネストされた宣言のみをレンダリングします。maxdepth が 0 または 2 以上であることが必要です。

バージョン 3.5 で追加。

制約付きテンプレート

警告

concept のサポートは実験的です。現在のドラフト標準と Concepts Technical Specification に基づいています。機能は進化するにつれて変更される可能性があります。

注記

Sphinx は現在 requires 句をサポートしていません。

プレースホルダー

宣言では、concept の名前を使用して制約付きテンプレートパラメータを導入したり、キーワード auto を使用して制約なしテンプレートパラメータを導入したりできます。

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

テンプレート導入

単純な制約付き関数またはクラステンプレートは、テンプレートパラメータリストの代わりに テンプレート導入 で宣言できます

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

これらは次のようにレンダリングされます。

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

Iterator であるように制約されたテンプレートパラメータを持つ関数テンプレート。

std::LessThanComparable{T}
class MySortedContainer

LessThanComparable であるように制約されたテンプレートパラメータを持つクラステンプレート。

ただし、パラメータの互換性についてはチェックが行われないことに注意してください。たとえば、Iterator{A, B, C} は有効な C++ ではない場合でも、導入として受け入れられます。

インライン式と型

:cpp:expr:
:cpp:texpr:

C++ 式または型を、インラインコード（cpp:expr）またはインラインテキスト（cpp:texpr）として挿入します。たとえば

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

は次のようにレンダリングされます。

int a = 42
int f(int i)

式: a * f(a) (またはテキストとして: a * f(a))。

型: const MySortedContainer<int>& (またはテキストとして const MySortedContainer<int>&)。

バージョン 1.7 で追加: cpp:expr ロール。

バージョン 1.8 で追加: cpp:texpr ロール。

名前空間化

C++ドメインでの宣言は、デフォルトでグローバルスコープに配置されます。現在のスコープは、3つの名前空間ディレクティブを使用して変更できます。それらは宣言のスタックを管理し、cpp:namespace はスタックをリセットし、与えられたスコープを変更します。

cpp:namespace-push ディレクティブは、スコープを現在のスコープの与えられた内側のスコープに変更します。

cpp:namespace-pop ディレクティブは、最も最近の cpp:namespace-push ディレクティブを元に戻します。

.. cpp:namespace:: スコープ 指定

後続のオブジェクトの現在のスコープを与えられたスコープに変更し、名前空間ディレクティブスタックをリセットします。名前空間はC++の名前空間に対応する必要はなく、クラスの名前で終わることもできることに注意してください。例えば、

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

後続のすべてのオブジェクトは、名前がスコープを前置して宣言されたかのように定義されます。後続の相互参照は、現在のスコープから検索が開始されます。

NULL、0、または nullptr をスコープとして使用すると、グローバルスコープに変更されます。

名前空間の宣言は、例えば、テンプレート化することもできます。

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

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

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

size をクラステンプレート std::vector のメンバー関数として宣言します。同様に、これは以下を使用して宣言することもできました。

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

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

または

.. cpp:class:: template<typename T> \
               std::vector
.. cpp:namespace-push:: スコープ 指定

現在のスコープを基準としてスコープを変更します。たとえば、次の後、

.. cpp:namespace:: A::B

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

現在のスコープは A::B::C::D になります。

バージョン 1.4 で追加。

.. cpp:namespace-pop::

前の cpp:namespace-push ディレクティブを元に戻します（単にスコープをポップするだけではありません）。たとえば、次の後、

.. cpp:namespace:: A::B

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

.. cpp:namespace-pop::

現在のスコープは A::B になります（A::B::C ではなく）。

前の cpp:namespace-push ディレクティブが使用されておらず、cpp:namespace ディレクティブのみが使用されている場合、現在のスコープはグローバルスコープにリセットされます。つまり、.. cpp:namespace:: A::B は、以下と同等です。

.. cpp:namespace:: nullptr

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

バージョン 1.4 で追加。

情報フィールドリスト

エンティティを宣言するためのすべてのC++ディレクティブは、次の情報フィールドをサポートしています（情報フィールドリストも参照してください）。

  • tparam: テンプレートパラメータの説明。

cpp:function ディレクティブは、さらに次のフィールドをサポートしています。

  • param、parameter、arg、argument: パラメータの説明。

  • returns、return: 戻り値の説明。

  • retval、retvals: 関数の結果を記述するための returns の代替。

  • throws、throw、exception: スローされる可能性のある例外の説明。

バージョン 4.3 で追加: retval フィールド型。

相互参照

これらのロールは、与えられた宣言型にリンクします。

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

名前でC++宣言を参照します（詳細は下記を参照）。名前は、リンクの位置に対して適切に修飾されている必要があります。

バージョン 2.0 で追加: cpp:struct ロールは、cpp:class ロールのエイリアスです。

テンプレートパラメータ/引数を持つ参照に関する注意

これらのロールは、Sphinxの相互参照構文ルールに従います。これは、(部分)テンプレートの特殊化を参照する場合は注意が必要であることを意味します。例えば、リンクが次のようになっている場合： :cpp:class:`MyClass<int>`。これは、MyClass というタイトルで int へのリンクとして解釈されます。この場合、次のように、開き山括弧をバックスラッシュでエスケープします： :cpp:class:`MyClass\<int>`。

カスタムタイトルが必要ない場合は、インライン式用のロールである cpp:expr および cpp:texpr を使用すると便利な場合があります。ここでは山括弧をエスケープする必要はありません。

テンプレートパラメータとテンプレート引数を持たない宣言

テンプレート化されていない宣言にリンクするには、名前はネストされた名前である必要があります。例えば、f または MyClass::f。

オーバーロードされた（メンバー）関数

(メンバー)関数が名前だけで参照されている場合、参照は任意のオーバーロードに一致するものを指します。cpp:any ロールと cpp:func ロールは、完全な関数宣言である代替形式を使用します。これにより、正確に一致するオーバーロードに解決されます。例として、次のクラス宣言を考えてみましょう。

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

cpp:func ロールを使った参照

add_function_parentheses 設定変数は、特定のオーバーロードの参照には影響しないことに注意してください。

テンプレート宣言

以下の宣言を想定します。

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

一般に、参照には、修飾名のプレフィックスのテンプレートパラメータ宣言とテンプレート引数を含める必要があります。例えば

  • 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)

現在、ルックアップは、テンプレートパラメータ識別子が等しい文字列の場合にのみ成功します。つまり、template<typename UOuter> Wrapper::Outer は機能しません。

省略記法として、テンプレートパラメータリストが省略された場合、ルックアップはプライマリテンプレートまたは非テンプレートのいずれかを想定しますが、部分テンプレート特殊化は想定しません。これは、以下の参照も機能することを意味します

(完全な)テンプレート特殊化

以下の宣言を想定します。

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

一般に、参照には、各テンプレート引数リストのテンプレートパラメータリストを含める必要があります。したがって、上記の完全特殊化は、template<> Outer<int> (template<> Outer<int>) および template<> template<> Outer<int>::Inner<bool> (template<> template<> Outer<int>::Inner<bool>) で参照できます。省略記法として、空のテンプレートパラメータリストを省略できます。例えば、Outer<int> (Outer<int>) および Outer<int>::Inner<bool> (Outer<int>::Inner<bool>) などです。

部分テンプレート特殊化

以下の宣言を想定します。

template<typename T>
class Outer<T*>

部分特殊化への参照は、常にテンプレートパラメータリストを含める必要があります。例えば、template<typename T> Outer<T*> (template<typename T> Outer<T*>) などです。現在、ルックアップは、テンプレートパラメータ識別子が等しい文字列の場合にのみ成功します。

構成変数

C++ドメインのオプションを参照してください。