C++领域

Added in version 1.0.

C++域（名称**cpp**）支持文档化C++项目.

直接声明实体的指令

以下指令可用.所有声明可以以可见性语句（ public 、 private 或 protected ）开头.

.. cpp:class:: class specifier

.. cpp:struct:: class specifier

描述一个类/结构体,可能包括继承的规范,例如:

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

The difference between cpp:class and cpp:struct is only cosmetic: the prefix rendered in the output, and the specifier shown in the index.

类可以直接在嵌套作用域内声明,例如::

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

Added in version 2.0: The cpp:struct directive.

.. 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: (no value)

确保函数的参数将在单个逻辑行上发出,覆盖 cpp_maximum_signature_line_length 和 maximum_signature_line_length .

Added in version 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

描述一个（作用域限定的）枚举,可能包含指定的基础类型.任何在无作用域枚举内部声明的枚举成员,将同时在枚举作用域和父作用域中声明.示例:

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

描述一个联合.

Added in version 1.8.

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

警告

对于概念的支持仍处于实验阶段.它基于当前的草案标准和概念技术规范.随着它们的发展,功能可能会发生变化.

描述一个概念.它必须具有恰好一个模板参数列表.名称可以是嵌套名称.示例:

.. 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 可递增时.

Added in version 1.5.

选项

一些指令支持选项:

• :no-index-entry: and :no-contents-entry:, see 基本标记.

• :tparam-line-spec:`` ,用于模板声明.如果指定,每个模板参数将被渲染在单独的一行上.

  Added in version 1.6.

匿名实体

C++支持匿名命名空间、类、枚举和联合体.为了文档的需要,它们必须被赋予一个以 @ 开头的名称,例如 @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 .

Added in version 1.8.

别名声明

有时,在主要文档以外的地方列出声明可能会很有帮助,例如,在创建类接口的概要时.可以使用以下指令达到此目的.

.. cpp:alias:: name or function signature

插入一个或多个别名声明.每个实体可以像在 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()

whereas:

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

Added in version 2.0.

选项

:maxdepth: int

插入嵌套的声明,直到给定的总深度.使用0表示无限深度,使用1表示仅提到的声明.默认为1.

Added in version 3.5.

:noroot:

跳过提到的声明,仅渲染嵌套声明.需要 maxdepth 要么为 0,要么至少为 2.

Added in version 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.

模板介绍

可以用 template introduction 而不是模板参数列表声明简单的受限函数或类模板:

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

一个类模板,其中模板参数被限制为可比较的较小值.

请注意,关于参数兼容性不会进行检查.例如, 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>& ）.

Added in version 1.7: The cpp:expr role.

Added in version 1.8: The cpp:texpr role.

命名空间

在C++领域,声明默认放置在全局作用域中.当前作用域可以使用三种命名空间指令进行更改.它们管理一个堆栈声明,其中 cpp:namespace 重置堆栈并更改给定作用域.

The cpp:namespace-push directive changes the scope to a given inner scope of the current one.

The cpp:namespace-pop directive undoes the most recent cpp:namespace-push directive.

.. cpp:namespace:: scope specification

将当前范围更改为给定范围,并重置命名空间指令栈.请注意,命名空间不需要对应于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:: scope specification

将范围相对于当前范围进行更改.例如,在:

.. cpp:namespace:: A::B

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

当前作用域为 A ::B::C::D .

Added in version 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

Added in version 1.4.

信息字段列表

所有用于声明实体的C++指令都支持以下信息字段（另请参见 信息字段列表 ）:

• tparam: Description of a template parameter.

The cpp:function directive additionally supports the following fields:

• param, parameter, arg, argument: Description of a parameter.

• returns, return: Description of a return value.

• retval, retvals: An alternative to returns for describing the result of the function.

• throws, throw, exception: Description of a possibly thrown exception.

Added in version 4.3: The retval field type.

交叉引用

这些角色链接到给定的声明类型:

: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: The cpp:struct role as alias for the cpp:class role.

关于带模板参数/参数的引用的说明

这些角色遵循 Sphinx 交叉引用语法 规则.这意味着在引用（部分）模板特化时必须小心,例如如果链接看起来像这样::cpp:class:`MyClass<int> `` .这被解释为链接到 int `` ,标题为`` MyClass `` .在这种情况下,请用反斜杠转义开头的尖括号,如下所示:`` MyClass<int>` .

当不需要自定义标题时,使用内联表达式的角色可能会很有用,:rst:role:cpp:expr 和 cpp:texpr ,在这里尖括号无需转义.

没有模板参数和模板参数的声明

对于链接到非模板声明,名称必须是嵌套名称,例如 f 或 MyClass::f .

重载（成员）函数

当仅使用函数名称引用（成员）函数时,该引用将指向任意匹配的重载.:rst:role: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 ,:cpp:func:C::f

• 也可以任意重载 :C::f() , :cpp C::f()

• 特定重载: void C ::f() ,:cpp:func:void C::f()

• 特定重载: void C ::f(int) , void C::f(int)

• 特定重载 :void C::f(double) , :cpp void C::f(double)()

• 特定重载 :void C::f(double) const , :cpp void C::f(double) const()

注意,:confval: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

C域

Next

JavaScript领域