O domínio C++

Adicionado na versão 1.0.

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

Diretivas para declarar entidades

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

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

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

A diferença entre cpp:class e cpp:struct é apenas cosmética: o prefixo renderizado na saída e o especificador mostrado no índice.

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: A diretiva cpp:struct.

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

Garante que os parâmetros da função serão emitidos em uma única linha lógica, substituindo cpp_maximum_signature_line_length e 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

Descreve um enum (com escopo definido), possivelmente com o tipo subjacente especificado. Quaisquer enumeradores declarados dentro de um enum sem escopo serão declarados no escopo do enum e no escopo pai. Exemplos:

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

Descreve uma união.

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: e :no-contents-entry:, veja Marcação básica.

  • :tparam-line-spec:, para declarações com modelo. Se especificado, cada parâmetro do modelo será renderizado em uma linha separada.

    Adicionado na versão 1.6.

Entidades anônimas

C++ oferece suporte a espaços de nomes, classes, enumerações e uniões anônimas. Para fins de documentação, eles devem receber algum nome que comece com @, por exemplo, @42 ou @data. Esses nomes também podem ser usados ​​em referências cruzadas e expressões (de tipo), embora símbolos aninhados sejam encontrados mesmo quando omitidos. O nome @... sempre será renderizado como [anonymous] (possivelmente como um 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`.

Isso será renderizado como:

class Data
union [anonymous]
int a
double b

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

Adicionado na versão 1.8.

Fazendo alias de declarações

Às vezes, declarações de lista podem ser úteis em outros lugares além da documentação principal, por exemplo, ao criar uma sinopse de uma interface de classe. A seguinte diretiva pode ser usada para esse propósito.

.. cpp:alias:: name or function signature

Insere uma ou mais declarações de alias. Cada entidade pode ser especificada como pode no papel cpp:any. Se o nome de uma função for fornecido (em oposição à assinatura completa), todas as sobrecargas da função serão listadas.

Por exemplo:

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

se torna

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

enquanto:

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

se torna

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

Adicionado na versão 2.0.

Opções

:maxdepth: int

Insere também declarações aninhadas, até a profundidade total fornecida. Use 0 para profundidade infinita e 1 apenas para a declaração mencionada. O padrão é 1.

Adicionado na versão 3.5.

:noroot:

Ignora as declarações mencionadas e renderiza apenas declarações aninhadas. Requer maxprofundidade 0 ou pelo menos 2.

Adicionado na versão 3.5.

Modelos restritos

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

O Sphinx atualmente não tem suporte a cláusulas requires.

Espaços reservados

As declarações podem usar o nome de um conceito para introduzir parâmetros de modelo restritos, ou a palavra-chave auto para introduzir parâmetros de modelo irrestrito:

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

Introduções de modelos

Modelos restritos simples de classe e função podem ser declarados com uma introdução de modelo em vez de uma lista de parâmetros de modelo:

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

Eles são renderizados da seguinte maneira.

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.

Observe, entretanto, que nenhuma verificação é realizada com relação à compatibilidade dos parâmetros. Por exemplo, Iterator{A, B, C} será aceito como uma introdução mesmo que não seja C++ válido.

Tipos e expressões em lniha

:cpp:expr:
:cpp:texpr:

Insere uma expressão C++ ou digite como código embutido (cpp:expr) ou texto embutido (cpp:texpr). Por exemplo:

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

será renderizado da seguinte maneira:

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: O papel cpp:expr.

Adicionado na versão 1.8: O papel cpp:texpr.

Usando espaços de nomes

As declarações no domínio C++ são colocadas por padrão no escopo global. O escopo atual pode ser alterado usando três diretivas de espaço de nomes. Eles gerenciam declarações de pilha onde cpp:namespace redefine a pilha e altera um determinado escopo.

A diretiva cpp:namespace-push altera o escopo para um determinado escopo interno do atual.

A diretiva cpp:namespace-pop desfaz a diretiva cpp:namespace-push mais recente.

.. cpp:namespace:: scope specification

Altera o escopo atual dos objetos subsequentes para o escopo especificado e redefine a pilha de diretivas de espaço de nomes. Observe que o espaço de nomes não precisa corresponder aos espaços de nomes C++, mas pode terminar em nomes de classes, por exemplo:

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

Todos os objetos subsequentes serão definidos como se seus nomes tivessem sido declarados com o escopo anexado. As referências cruzadas subsequentes serão pesquisadas a partir do escopo atual.

Usar NULL, 0 ou nullptr como escopo mudará para escopo global.

Uma declaração de espaço de nomes também pode ser modelada, por exemplo,:

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

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

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

declara size como uma função membro do modelo de classe std::vector. De forma equivalente, isso poderia ter sido declarado usando:

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

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

ou:

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

Altera o escopo relativamente ao escopo atual. Por exemplo, depois de:

.. cpp:namespace:: A::B

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

o escopo atual será A::B::C::D.

Adicionado na versão 1.4.

.. cpp:namespace-pop::

Desfaz a diretiva cpp:namespace-push anterior (não apenas abre um escopo). Por exemplo, depois de:

.. cpp:namespace:: A::B

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

.. cpp:namespace-pop::

o escopo atual será A::B (não A::B::C).

Se nenhuma diretiva cpp:namespace-push anterior tiver sido usada, mas apenas uma diretiva cpp:namespace, então o escopo atual será redefinido para o escopo global. Ou seja, .. cpp:namespace:: A::B é equivalente a:

.. cpp:namespace:: nullptr

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

Adicionado na versão 1.4.

Lista de campos de informações

Todas as diretivas C++ para declaração de entidades têm suporte aos seguintes campos de informação (veja também Listas de campos de informações):

  • tparam: Descrição de um parâmetro de modelo.

A diretiva cpp:function tem suporte adicionalmente aos seguintes campos:

  • param, parameter, arg, argument: Descrição de um parâmetro.

  • returns, return: Descrição de um valor de retorno.

  • retval, retvals: Uma alternativa a returns para descrever o resultado da função.

  • throws, throw, exception: Descrição de uma exceção possivelmente lançada.

Adicionado na versão 4.3: O tipo de campo retval.

Fazendo referência cruzada

Esses papéis estão vinculados aos tipos de declaração fornecidos:

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

Faz referência a uma declaração C++ por nome (veja detalhes abaixo). O nome deve ser devidamente qualificado em relação à posição do link.

Adicionado na versão 2.0: O papel cpp:struct como um alias para o papel cpp:class.

Nota sobre referências com parâmetros/argumentos de modelos

Esses papéis seguem as regras de Syntax do Sphinx. Isso significa que deve-se ter cuidado ao fazer referência a uma especialização de modelo (parcial), por exemplo. se o link for assim: :cpp:class:`MinhaClasse<int>`. Isto é interpretado como um link para int com o título MinhaClasse. Nesse caso, escape o sinal de maior que com uma barra invertida, como esta: :cpp:class:`MinhaClasse\<int>`.

Quando um título personalizado não é necessário, pode ser útil usar os papéis para expressões em linha, cpp:expr e cpp:texpr, onde os sinais de maior que não precisam de escape.

Declarações sem parâmetros de modelo e argumentos de modelo

Para vincular a declarações não modeladas, o nome deve ser um nome aninhado, por exemplo, f ou MinhaClasse::f.

Funções (membro) sobrecarregadas

Quando uma função (membro) é referenciada usando apenas seu nome, a referência apontará para uma sobrecarga de correspondência arbitrária. Os papéis cpp:any e cpp:func usam um formato alternativo, que é simplesmente uma declaração de função completa. Isso resolverá a sobrecarga de correspondência exata. Como exemplo, considere a seguinte declaração de classe:

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

Referências usando o papel cpp:func:

Observe que a variável de configuração add_function_parentheses não influencia referências de sobrecarga específicas.

Declarações modeladas

Considere as seguintes declarações.

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

Em geral, a referência deve incluir as declarações de parâmetros do modelo e os argumentos do modelo para o prefixo dos nomes qualificados. Por exemplo:

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

Atualmente, a pesquisa só é bem-sucedida se os identificadores dos parâmetros do modelo forem strings iguais. Ou seja, template\<typename UOuter> Wrapper::Outer não funcionará.

Como uma notação abreviada, se uma lista de parâmetros do modelo for omitida, a pesquisa presumirá um modelo primário ou um não modelo, mas não uma especialização parcial do modelo. Isso significa que as seguintes referências também funcionam:

Especializações (completas) de modelos

Considere as seguintes declarações.

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

Em geral, a referência deve incluir uma lista de parâmetros de modelo para cada lista de argumentos de modelo. A especialização completa acima pode, portanto, ser referenciada com template\<> Outer\<int> (template<> Outer<int>) e template\<> template\<> Outer\<int>::Inner\<bool> (template<> template<> Outer<int>::Inner<bool>). Como abreviação, a lista de parâmetros do modelo vazio pode ser omitida, por exemplo, Outer\<int> (Outer<int>) e Outer\<int>::Inner\<bool> (Outer<int>::Inner<bool>).

Especializações parciais de modelo

Considere a seguinte declaração.

template<typename T>
class Outer<T*>

Referências a especializações parciais devem sempre incluir as listas de parâmetros do modelo, por exemplo, template\<typename T> Outer\<T*> (template<typename T> Outer<T*> ). Atualmente, a pesquisa só é bem-sucedida se os identificadores dos parâmetros do modelo forem strings iguais.

Variáveis de configuração

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