O domínio C++

Adicionado na versão 1.0.

O domínio C++ (nome cpp) oferece suporte a documentar projetos C++.

Directives for Declaring Entities

As seguintes diretivas estão disponíveis. Todas as declarações podem começar com uma declaração de visibilidade (public, private ou protected).

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

Descreva uma classe/struct, possivelmente com especificação de herança, por exemplo:

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

A classe pode ser declarada diretamente dentro de um escopo aninhado, por exemplo:

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

Um modelo de classe pode ser declarado:

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

ou com uma quebra de linha:

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

As especializações de modelo completas e parciais podem ser declaradas:

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

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

Adicionado na versão 2.0: The cpp:struct directive.

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

Descreve uma função ou função-membro, por exemplo:

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

Os modelos de função também podem ser descritos:

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

e especializações de modelo de função:

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

Ensures that the function’s parameters will be emitted on a single logical line, overriding cpp_maximum_signature_line_length and maximum_signature_line_length.

Adicionado na versão 7.1.

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

Descreve uma variável ou variável de membro, por exemplo:

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

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

.. cpp:member:: int a = 42

Os modelos de variáveis também podem ser descritos:

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

Descreve um tipo como em uma declaração de typedef, uma declaração de alias de tipo ou simplesmente o nome de um tipo com tipo não especificado, por exemplo:

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

Um alias de tipo também pode ser modelado:

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

Os exemplos são renderizados como demonstrado a seguir.

typedef std::vector<int> MyList

Uma declaração semelhante a typedef de um tipo.

type MyContainer::const_iterator

Declaração de um alias de tipo com tipo não especificado.

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

Declaração de um alias de tipo.

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

Describe a (scoped) enum, possibly with the underlying type specified. Any enumerators declared inside an unscoped enum will be declared both in the enum scope and in the parent scope. Examples:

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

Descreve um enumerador, opcionalmente com seu valor definido, por exemplo:

.. cpp:enumerator:: MyEnum::myEnumerator

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

Describe a union.

Adicionado na versão 1.8.

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

Aviso

O suporte para conceitos é experimental. Baseia-se no projeto de padrão atual e na Especificação Técnica dos Conceitos. Os recursos podem mudar à medida que evoluem.

Descreve um conceito. Deve ter exatamente 1 lista de parâmetros de modelo. O nome pode ser um nome aninhado. Exemplo:

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

Isso será renderizado da seguinte forma:

template<typename It>
concept std::Iterator

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

Notation

It r

An lvalue.

Valid Expressions

  • *r, when r is dereferenceable.

  • ++r, with return type It&, when r is incrementable.

Adicionado na versão 1.5.

Opções

Algumas diretivas oferecem suporte às opções:

  • :no-index-entry: and :no-contents-entry:, see Marcação Básica.

  • :tparam-line-spec:, for templated declarations. If specified, each template parameter will be rendered on a separate line.

    Adicionado na versão 1.6.

Anonymous Entities

C++ supports anonymous namespaces, classes, enums, and unions. For the sake of documentation they must be given some name that starts with @, e.g., @42 or @data. These names can also be used in cross-references and (type) expressions, though nested symbols will be found even when omitted. The @... name will always be rendered as [anonymous] (possibly as a link).

Exemplo:

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

This will be rendered as:

class Data
union [anonymous]
int a
double b

Explicit ref: Data::[anonymous]::a. Short-hand ref: Data::a.

Adicionado na versão 1.8.

Aliasing Declarations

Sometimes it may be helpful list declarations elsewhere than their main documentation, e.g., when creating a synopsis of a class interface. The following directive can be used for this purpose.

.. cpp:alias:: name or function signature

Insert one or more alias declarations. Each entity can be specified as they can in the cpp:any role. If the name of a function is given (as opposed to the complete signature), then all overloads of the function will be listed.

Por exemplo:

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

becomes

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)

becomes

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

Adicionado na versão 2.0.

Opções

:maxdepth: int

Insert nested declarations as well, up to the total depth given. Use 0 for infinite depth and 1 for just the mentioned declaration. Defaults to 1.

Adicionado na versão 3.5.

:noroot:

Skip the mentioned declarations and only render nested declarations. Requires maxdepth either 0 or at least 2.

Adicionado na versão 3.5.

Constrained Templates

Aviso

O suporte para conceitos é experimental. Baseia-se no projeto de padrão atual e na Especificação Técnica dos Conceitos. Os recursos podem mudar à medida que evoluem.

Nota

Sphinx does not currently support requires clauses.

Placeholders

Declarations may use the name of a concept to introduce constrained template parameters, or the keyword auto to introduce unconstrained template parameters:

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

Simple constrained function or class templates can be declared with a template introduction instead of a template parameter list:

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

They are rendered as follows.

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

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

std::LessThanComparable{T}
class MySortedContainer

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

Note however that no checking is performed with respect to parameter compatibility. E.g., Iterator{A, B, C} will be accepted as an introduction even though it would not be valid C++.

Inline Expressions and Types

:cpp:expr:
:cpp:texpr:

Insert a C++ expression or type either as inline code (cpp:expr) or inline text (cpp:texpr). For example:

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

will be rendered as follows:

int a = 42
int f(int i)

An expression: a * f(a) (or as text: a * f(a)).

A type: const MySortedContainer<int>& (or as text const MySortedContainer<int>&).

Adicionado na versão 1.7: The cpp:expr role.

Adicionado na versão 1.8: The cpp:texpr role.

Namespacing

Declarations in the C++ domain are as default placed in global scope. The current scope can be changed using three namespace directives. They manage a stack declarations where cpp:namespace resets the stack and changes a given scope.

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

Changes the current scope for the subsequent objects to the given scope, and resets the namespace directive stack. Note that the namespace does not need to correspond to C++ namespaces, but can end in names of classes, e.g.,:

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

All subsequent objects will be defined as if their name were declared with the scope prepended. The subsequent cross-references will be searched for starting in the current scope.

Using NULL, 0, or nullptr as the scope will change to global scope.

A namespace declaration can also be templated, e.g.,:

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

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

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

declares size as a member function of the class template std::vector. Equivalently this could have been declared using:

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

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

or:

.. cpp:class:: template<typename T> \
               std::vector
.. cpp:namespace-push:: scope specification

Change the scope relatively to the current scope. For example, after:

.. cpp:namespace:: A::B

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

the current scope will be A::B::C::D.

Adicionado na versão 1.4.

.. cpp:namespace-pop::

Undo the previous cpp:namespace-push directive (not just pop a scope). For example, after:

.. cpp:namespace:: A::B

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

.. cpp:namespace-pop::

the current scope will be A::B (not A::B::C).

If no previous cpp:namespace-push directive has been used, but only a cpp:namespace directive, then the current scope will be reset to global scope. That is, .. cpp:namespace:: A::B is equivalent to:

.. cpp:namespace:: nullptr

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

Adicionado na versão 1.4.

Lista Informação Campos

All the C++ directives for declaring entities support the following info fields (see also Lista Informação Campos):

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

Adicionado na versão 4.3: The retval field type.

Cross-referencing

These roles link to the given declaration types:

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

Reference a C++ declaration by name (see below for details). The name must be properly qualified relative to the position of the link.

Adicionado na versão 2.0: The cpp:struct role as alias for the cpp:class role.

Note on References with Templates Parameters/Arguments

These roles follow the Sphinx Sintaxe de referência cruzada rules. This means care must be taken when referencing a (partial) template specialization, e.g. if the link looks like this: :cpp:class:`MyClass<int>`. This is interpreted as a link to int with a title of MyClass. In this case, escape the opening angle bracket with a backslash, like this: :cpp:class:`MyClass\<int>`.

When a custom title is not needed it may be useful to use the roles for inline expressions, cpp:expr and cpp:texpr, where angle brackets do not need escaping.

Declarations without template parameters and template arguments

For linking to non-templated declarations the name must be a nested name, e.g., f or MyClass::f.

Overloaded (member) functions

When a (member) function is referenced using just its name, the reference will point to an arbitrary matching overload. The cpp:any and cpp:func roles use an alternative format, which simply is a complete function declaration. This will resolve to the exact matching overload. As example, consider the following class declaration:

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

References using the cpp:func role:

Note that the add_function_parentheses configuration variable does not influence specific overload references.

Templated declarations

Assume the following declarations.

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

In general the reference must include the template parameter declarations, and template arguments for the prefix of qualified names. For example:

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

Currently the lookup only succeed if the template parameter identifiers are equal strings. That is, template\<typename UOuter> Wrapper::Outer will not work.

As a shorthand notation, if a template parameter list is omitted, then the lookup will assume either a primary template or a non-template, but not a partial template specialisation. This means the following references work as well:

(Full) Template Specialisations

Assume the following declarations.

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

In general the reference must include a template parameter list for each template argument list. The full specialisation above can therefore be referenced with template\<> Outer\<int> (template<> Outer<int>) and template\<> template\<> Outer\<int>::Inner\<bool> (template<> template<> Outer<int>::Inner<bool>). As a shorthand the empty template parameter list can be omitted, e.g., Outer\<int> (Outer<int>) and Outer\<int>::Inner\<bool> (Outer<int>::Inner<bool>).

Partial Template Specialisations

Assume the following declaration.

template<typename T>
class Outer<T*>

References to partial specialisations must always include the template parameter lists, e.g., template\<typename T> Outer\<T*> (template<typename T> Outer<T*>). Currently the lookup only succeed if the template parameter identifiers are equal strings.

Configuration Variables

See Opções para domínio C++.