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:: （成員） 函數 原型

描述函數或成員函數，例如：

.. 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:: （成員） 變數 宣告

.. cpp:var:: （成員） 變數 宣告

描述變數或成員變數，例如：

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

.. cpp:type:: 名稱

.. cpp:type:: 類型 別名 宣告

描述類型，如 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 宣告

.. cpp:enum-struct:: scoped enum 宣告

.. cpp:enum-class:: scoped enum 宣告

描述（作用域）列舉，可能指定了底層類型。在 unscoped 列舉中宣告的任何列舉器都將在列舉範圍和父範圍中宣告。範例

.. 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:: 名稱

.. cpp:enumerator:: 名稱 = 常數

描述列舉器，可選地定義其值，例如：

.. cpp:enumerator:: MyEnum::myEnumerator

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

.. cpp:union:: 名稱

描述聯合。

在版本 1.8 中新增。

.. cpp:concept:: template-parameter-list 名稱

警告

對概念的支援是實驗性的。它基於當前草案標準和概念技術規範。這些功能可能會隨著它們的發展而改變。

描述概念。它必須正好有 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++ 支援匿名命名空間、類別、列舉和聯合。為了文件化的目的，它們必須給定一些以 @ 開頭的名稱，例如，@42 或 @data。這些名稱也可以在交叉引用和（類型）表達式中使用，即使省略了巢狀符號，也會找到它們。@... 名稱將始終呈現為 [匿名]（可能作為連結）。

範例

.. 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 [匿名]

int a

double b

顯式參考：Data::[anonymous]::a。簡寫參考：Data::a。

在版本 1.8 中新增。

別名宣告

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

.. cpp:alias:: 名稱 或 函數 簽名

插入一個或多個別名宣告。每個實體都可以像在 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 中新增。

受限模板

警告

對概念的支援是實驗性的。它基於當前草案標準和概念技術規範。這些功能可能會隨著它們的發展而改變。

注意

Sphinx 目前不支援 requires 子句。

佔位符

宣告可以使用概念名稱來引入受限模板參數，或使用關鍵字 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:

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

.. 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++ 網域中的宣告預設放置在全域範圍中。可以使用三個命名空間指令來變更目前範圍。它們管理堆疊宣告，其中 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++ 宣告的名稱 (詳情請見下方)。名稱必須相對於連結位置進行適當的限定。

Added in version 2.0: cpp:struct role 作為 cpp:class role 的別名，已於版本 2.0 中新增。

關於帶有模板參數/引數的參考的注意事項

這些角色遵循 Sphinx 語法 規則。這表示在參考 (部分) 模板特化時必須小心，例如，如果連結看起來像這樣：:cpp:class:`MyClass<int>`。這會被解讀為連結到 int，標題為 MyClass。在這種情況下，請使用反斜線跳脫左角括號，像這樣：: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 角色的參考

• 任意多載：C::f、 C::f()

• 也是任意多載：C::f()、 C::f()

• 特定多載：void C::f()、 void C::f()

• 特定多載：void C::f(int)、 void C::f(int)

• 特定多載：void C::f(double)、 void C::f(double)

• 特定多載：void C::f(double) const、 void C::f(double) const

請注意，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 將無法運作。

作為簡寫符號，如果省略了模板參數列表，則查找將假定為主模板或非模板，但不是部分模板特化。這表示以下參考也有效

• Wrapper::Outer (Wrapper::Outer)

• Wrapper::Outer::Inner (Wrapper::Outer::Inner)

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

(完整) 模板特化

假設以下宣告。

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

Previous

The C Domain

Next

The JavaScript Domain