Sphinx

# The C++ Domain

Added in version 1.0.

The C++ domain (name cpp) supports documenting C++ projects.

## Directives for Declaring Entities

The following directives are available. All declarations can start with a visibility statement (`public`, `private` or `protected`).

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

  Describe a class/struct, possibly with specification of inheritance, e.g.,:

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

  The class can be directly declared inside a nested scope, e.g.,:

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

  A class template can be declared:

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

  or with a line break:

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

  Full and partial template specialisations can be declared:

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

  Describe a function or member function, e.g.,:

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

  Function templates can also be described:

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

  and function template specialisations:

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

    Added in version 7.1.

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

  Describe a variable or member variable, e.g.,:

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

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

      .. cpp:member:: int a = 42

  Variable templates can also be described:

      .. cpp:member:: template<class T> \
                      constexpr T pi = T(3.1415926535897932385)

.. cpp:type:: typedef declaration
.. cpp:type:: name
.. cpp:type:: type alias declaration

  Describe a type as in a typedef declaration, a type alias declaration, or simply the name of a type with unspecified type, e.g.,:

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

  A type alias can also be templated:

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

  The example are rendered as follows.

  typedef std::vector<int> MyList

    A typedef-like declaration of a type.

  type MyContainer::const_iterator

    Declaration of a type alias with unspecified type.

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

    Declaration of a type alias.

  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

  Describe an enumerator, optionally with its value defined, e.g.,:

      .. cpp:enumerator:: MyEnum::myEnumerator

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

.. cpp:union:: name

  Describe a union.

  Added in version 1.8.

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

  Warning

  The support for concepts is experimental. It is based on the current draft standard and the Concepts Technical Specification. The features may change as they evolve.

  Describe a concept. It must have exactly 1 template parameter list. The name may be a nested name. Example:

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

  This will render as follows:

  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.

  Added in version 1.5.

### Options

Some directives support options:

- `:no-index-entry:` and `:no-contents-entry:`, see Basic Markup.

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

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

Example:

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

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

  For example:

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

  Added in version 2.0.

  Options

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

    Added in version 3.5.

  :noroot:

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

    Added in version 3.5.

## Constrained Templates

Warning

The support for concepts is experimental. It is based on the current draft standard and the Concepts Technical Specification. The features may change as they evolve.

Note

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

  Added in version 1.7: The `cpp:expr` role.

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

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

  Added in version 1.4.

## Info field lists

All the C++ directives for declaring entities support the following info fields (see also Info field lists):

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

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

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

- Arbitrary overload: `C::f`, `C::f()`

- Also arbitrary overload: `C::f()`, `C::f()`

- Specific overload: `void C::f()`, `void C::f()`

- Specific overload: `void C::f(int)`, `void C::f(int)`

- Specific overload: `void C::f(double)`, `void C::f(double)`

- Specific overload: `void C::f(double) const`, `void C::f(double) const`

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:

- `Wrapper::Outer` (`Wrapper::Outer`)

- `Wrapper::Outer::Inner` (`Wrapper::Outer::Inner`)

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

### (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 Options for the C++ domain.