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:: 无作用域枚举声明¶

.. cpp:enum-struct:: 作用域枚举声明¶

.. cpp:enum-class:: 作用域枚举声明¶

描述（作用域）枚举，可能指定了底层类型。在无作用域枚举内声明的任何枚举器都将在枚举作用域和父作用域中声明。示例

.. 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:: 模板参数列表名称¶

警告

对概念的支持是实验性的。它基于当前草案标准和 Concepts Technical Specification。这些功能可能会随着发展而变化。

描述概念。它必须恰好有 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 版本中新增。

约束模板¶

警告

对概念的支持是实验性的。它基于当前草案标准和 Concepts Technical Specification。这些功能可能会随着发展而变化。

注意

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++ 声明（详细信息见下文）。名称必须相对于链接的位置进行正确限定。

在 2.0 版本中新增: cpp:struct 角色作为 cpp:class 角色的别名。

关于模板参数/实参引用的注意事项

这些角色遵循 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++ 域的选项。