From de3266ab25cfd122382e3463d6425178c2610c13 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Sun, 1 Oct 2023 19:05:22 +0100 Subject: [PATCH] Split out the C++ domain --- doc/usage/domains/cpp.rst | 729 ++++++++++++++++++++++++++++++++++++ doc/usage/domains/index.rst | 728 ----------------------------------- 2 files changed, 729 insertions(+), 728 deletions(-) create mode 100644 doc/usage/domains/cpp.rst diff --git a/doc/usage/domains/cpp.rst b/doc/usage/domains/cpp.rst new file mode 100644 index 000000000..141713b21 --- /dev/null +++ b/doc/usage/domains/cpp.rst @@ -0,0 +1,729 @@ +.. highlight:: rst + +.. _cpp-domain: + +The C++ Domain +-------------- + +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``). + +.. rst:directive:: .. 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 :rst:dir:`cpp:class` and :rst:dir:`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 std::array + + or with a line break:: + + .. cpp:class:: template \ + std::array + + Full and partial template specialisations can be declared:: + + .. cpp:class:: template<> \ + std::array + + .. cpp:class:: template \ + std::array + + .. versionadded:: 2.0 + The :rst:dir:`cpp:struct` directive. + +.. rst: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 \ + void print(U &&u) + + and function template specialisations:: + + .. cpp:function:: template<> \ + void print(int i) + + .. rst:directive:option:: single-line-parameter-list + :type: no value + + Ensures that the function's parameters will be emitted on a single logical + line, overriding :confval:`cpp_maximum_signature_line_length` and + :confval:`maximum_signature_line_length`. + + .. versionadded:: 7.1 + +.. rst:directive:: .. 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 \ + constexpr T pi = T(3.1415926535897932385) + +.. rst:directive:: .. 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 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 + + Declaration of a type alias. + + A type alias can also be templated:: + + .. cpp:type:: template \ + MyContainer = std::vector + + The example are rendered as follows. + + .. cpp:type:: std::vector MyList + :no-contents-entry: + :no-index-entry: + + A typedef-like declaration of a type. + + .. cpp:type:: MyContainer::const_iterator + :no-contents-entry: + :no-index-entry: + + Declaration of a type alias with unspecified type. + + .. cpp:type:: MyType = std::unordered_map + :no-contents-entry: + :no-index-entry: + + Declaration of a type alias. + + .. cpp:type:: template \ + MyContainer = std::vector + :no-contents-entry: + :no-index-entry: + +.. rst:directive:: .. 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::type + + A scoped enum with non-default visibility, and with a specified + underlying type. + +.. rst:directive:: .. 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 + +.. rst:directive:: .. cpp:union:: name + + Describe a union. + + .. versionadded:: 1.8 + +.. rst:directive:: .. 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 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: + + .. cpp:concept:: template 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. + + .. versionadded:: 1.5 + + +Options +^^^^^^^ + +Some directives support options: + +- ``:no-index-entry:`` and ``:no-contents-entry:``, see :ref:`basic-domain-markup`. +- ``:tparam-line-spec:``, for templated declarations. + If specified, each template parameter will be rendered on a separate line. + + .. versionadded:: 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: + +.. cpp:class:: Data + :no-contents-entry: + :no-index-entry: + + .. cpp:union:: @data + :no-contents-entry: + :no-index-entry: + + .. cpp:var:: int a + :no-contents-entry: + :no-index-entry: + + .. cpp:var:: double b + :no-contents-entry: + :no-index-entry: + +Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`. + +.. versionadded:: 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. + +.. rst:directive:: .. cpp:alias:: name or function signature + + Insert one or more alias declarations. Each entity can be specified + as they can in the :rst:role:`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 + + .. cpp:alias:: Data::a + overload_example::C::f + + whereas:: + + .. cpp:alias:: void overload_example::C::f(double d) const + void overload_example::C::f(double d) + + becomes + + .. cpp:alias:: void overload_example::C::f(double d) const + void overload_example::C::f(double d) + + .. versionadded:: 2.0 + + + .. rubric:: Options + + .. rst:directive:option:: 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. + + .. versionadded:: 3.5 + + .. rst:directive:option:: noroot + + Skip the mentioned declarations and only render nested declarations. + Requires ``maxdepth`` either 0 or at least 2. + + .. versionadded:: 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. + +.. cpp:function:: std::Iterator{It} void advance(It &it) + :no-contents-entry: + :no-index-entry: + + A function template with a template parameter constrained to be an Iterator. + +.. cpp:class:: std::LessThanComparable{T} MySortedContainer + :no-contents-entry: + :no-index-entry: + + 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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. rst:role:: 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&` + (or as text :cpp:texpr:`const MySortedContainer&`). + + will be rendered as follows: + + .. cpp:var:: int a = 42 + :no-contents-entry: + :no-index-entry: + + .. cpp:function:: int f(int i) + :no-contents-entry: + :no-index-entry: + + An expression: :cpp:expr:`a * f(a)` (or as text: :cpp:texpr:`a * f(a)`). + + A type: :cpp:expr:`const MySortedContainer&` + (or as text :cpp:texpr:`const MySortedContainer&`). + + .. versionadded:: 1.7 + The :rst:role:`cpp:expr` role. + + .. versionadded:: 1.8 + The :rst:role:`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. + +.. rst: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 \ + std::vector + + .. cpp:namespace:: template 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 \ + std::vector + + .. cpp:function:: std::size_t size() const + + or:: + + .. cpp:class:: template \ + std::vector + +.. rst:directive:: .. 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``. + + .. versionadded:: 1.4 + +.. rst:directive:: .. 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 + + .. versionadded:: 1.4 + +Info field lists +~~~~~~~~~~~~~~~~~ + +All the C++ directives for declaring entities support the following +info fields (see also :ref:`info-field-lists`): + +* ``tparam``: Description of a template parameter. + +The :rst:dir:`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. + +.. versionadded:: 4.3 + The ``retval`` field type. + +.. _cpp-roles: + +Cross-referencing +~~~~~~~~~~~~~~~~~ + +These roles link to the given declaration types: + +.. rst:role:: 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. + + .. versionadded:: 2.0 + The :rst:role:`cpp:struct` role as alias for the :rst:role:`cpp:class` + role. + +.. admonition:: Note on References with Templates Parameters/Arguments + + These roles follow the Sphinx :ref:`xref-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```. + 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\```. + + When a custom title is not needed it may be useful to use the roles for + inline expressions, :rst:role:`cpp:expr` and :rst:role:`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 :rst:role:`cpp:any` and :rst:role:`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: + +.. cpp:namespace-push:: overload_example +.. cpp:class:: C + + .. cpp:function:: void f(double d) const + .. cpp:function:: void f(double d) + .. cpp:function:: void f(int i) + .. cpp:function:: void f() + +References using the :rst:role:`cpp:func` role: + +- Arbitrary overload: ``C::f``, :cpp:func:`C::f` +- Also arbitrary overload: ``C::f()``, :cpp:func:`C::f()` +- Specific overload: ``void C::f()``, :cpp:func:`void C::f()` +- Specific overload: ``void C::f(int)``, :cpp:func:`void C::f(int)` +- Specific overload: ``void C::f(double)``, :cpp:func:`void C::f(double)` +- Specific overload: ``void C::f(double) const``, + :cpp:func:`void C::f(double) const` + +Note that the :confval:`add_function_parentheses` configuration variable +does not influence specific overload references. + +.. cpp:namespace-pop:: + + +Templated declarations +^^^^^^^^^^^^^^^^^^^^^^ + +Assume the following declarations. + +.. cpp:class:: Wrapper + + .. cpp:class:: template \ + Outer + + .. cpp:class:: template \ + Inner + +In general the reference must include the template parameter declarations, +and template arguments for the prefix of qualified names. For example: + +- ``template\ Wrapper::Outer`` + (:cpp:class:`template\ Wrapper::Outer`) +- ``template\ template\ Wrapper::Outer::Inner`` + (:cpp:class:`template\ template\ Wrapper::Outer::Inner`) + +Currently the lookup only succeed if the template parameter identifiers are +equal strings. That is, ``template\ 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`` + (:cpp:class:`Wrapper::Outer`) +- ``Wrapper::Outer::Inner`` + (:cpp:class:`Wrapper::Outer::Inner`) +- ``template\ Wrapper::Outer::Inner`` + (:cpp:class:`template\ Wrapper::Outer::Inner`) + +(Full) Template Specialisations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Assume the following declarations. + +.. cpp:class:: template \ + Outer + + .. cpp:class:: template \ + Inner + +.. cpp:class:: template<> \ + Outer + + .. cpp:class:: template \ + Inner + + .. cpp:class:: template<> \ + Inner + +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\`` (:cpp:class:`template\<> +Outer\`) and ``template\<> template\<> Outer\::Inner\`` +(:cpp:class:`template\<> template\<> Outer\::Inner\`). As a +shorthand the empty template parameter list can be omitted, e.g., +``Outer\`` (:cpp:class:`Outer\`) and ``Outer\::Inner\`` +(:cpp:class:`Outer\::Inner\`). + +Partial Template Specialisations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Assume the following declaration. + +.. cpp:class:: template \ + Outer + +References to partial specialisations must always include the template +parameter lists, e.g., ``template\ Outer\`` +(:cpp:class:`template\ Outer\`). Currently the lookup only +succeed if the template parameter identifiers are equal strings. + +Configuration Variables +~~~~~~~~~~~~~~~~~~~~~~~ + +See :ref:`cpp-config`. diff --git a/doc/usage/domains/index.rst b/doc/usage/domains/index.rst index e03eecd0d..0eea963a4 100644 --- a/doc/usage/domains/index.rst +++ b/doc/usage/domains/index.rst @@ -171,734 +171,6 @@ In short: refer to ``Queue.Queue.get`` but only display ``get`` as the link text. -.. _cpp-domain: - -The C++ Domain --------------- - -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``). - -.. rst:directive:: .. 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 :rst:dir:`cpp:class` and :rst:dir:`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 std::array - - or with a line break:: - - .. cpp:class:: template \ - std::array - - Full and partial template specialisations can be declared:: - - .. cpp:class:: template<> \ - std::array - - .. cpp:class:: template \ - std::array - - .. versionadded:: 2.0 - The :rst:dir:`cpp:struct` directive. - -.. rst: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 \ - void print(U &&u) - - and function template specialisations:: - - .. cpp:function:: template<> \ - void print(int i) - - .. rst:directive:option:: single-line-parameter-list - :type: no value - - Ensures that the function's parameters will be emitted on a single logical - line, overriding :confval:`cpp_maximum_signature_line_length` and - :confval:`maximum_signature_line_length`. - - .. versionadded:: 7.1 - -.. rst:directive:: .. 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 \ - constexpr T pi = T(3.1415926535897932385) - -.. rst:directive:: .. 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 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 - - Declaration of a type alias. - - A type alias can also be templated:: - - .. cpp:type:: template \ - MyContainer = std::vector - - The example are rendered as follows. - - .. cpp:type:: std::vector MyList - :no-contents-entry: - :no-index-entry: - - A typedef-like declaration of a type. - - .. cpp:type:: MyContainer::const_iterator - :no-contents-entry: - :no-index-entry: - - Declaration of a type alias with unspecified type. - - .. cpp:type:: MyType = std::unordered_map - :no-contents-entry: - :no-index-entry: - - Declaration of a type alias. - - .. cpp:type:: template \ - MyContainer = std::vector - :no-contents-entry: - :no-index-entry: - -.. rst:directive:: .. 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::type - - A scoped enum with non-default visibility, and with a specified - underlying type. - -.. rst:directive:: .. 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 - -.. rst:directive:: .. cpp:union:: name - - Describe a union. - - .. versionadded:: 1.8 - -.. rst:directive:: .. 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 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: - - .. cpp:concept:: template 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. - - .. versionadded:: 1.5 - - -Options -^^^^^^^ - -Some directives support options: - -- ``:no-index-entry:`` and ``:no-contents-entry:``, see :ref:`basic-domain-markup`. -- ``:tparam-line-spec:``, for templated declarations. - If specified, each template parameter will be rendered on a separate line. - - .. versionadded:: 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: - -.. cpp:class:: Data - :no-contents-entry: - :no-index-entry: - - .. cpp:union:: @data - :no-contents-entry: - :no-index-entry: - - .. cpp:var:: int a - :no-contents-entry: - :no-index-entry: - - .. cpp:var:: double b - :no-contents-entry: - :no-index-entry: - -Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`. - -.. versionadded:: 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. - -.. rst:directive:: .. cpp:alias:: name or function signature - - Insert one or more alias declarations. Each entity can be specified - as they can in the :rst:role:`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 - - .. cpp:alias:: Data::a - overload_example::C::f - - whereas:: - - .. cpp:alias:: void overload_example::C::f(double d) const - void overload_example::C::f(double d) - - becomes - - .. cpp:alias:: void overload_example::C::f(double d) const - void overload_example::C::f(double d) - - .. versionadded:: 2.0 - - - .. rubric:: Options - - .. rst:directive:option:: 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. - - .. versionadded:: 3.5 - - .. rst:directive:option:: noroot - - Skip the mentioned declarations and only render nested declarations. - Requires ``maxdepth`` either 0 or at least 2. - - .. versionadded:: 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. - -.. cpp:function:: std::Iterator{It} void advance(It &it) - :no-contents-entry: - :no-index-entry: - - A function template with a template parameter constrained to be an Iterator. - -.. cpp:class:: std::LessThanComparable{T} MySortedContainer - :no-contents-entry: - :no-index-entry: - - 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 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. rst:role:: 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&` - (or as text :cpp:texpr:`const MySortedContainer&`). - - will be rendered as follows: - - .. cpp:var:: int a = 42 - :no-contents-entry: - :no-index-entry: - - .. cpp:function:: int f(int i) - :no-contents-entry: - :no-index-entry: - - An expression: :cpp:expr:`a * f(a)` (or as text: :cpp:texpr:`a * f(a)`). - - A type: :cpp:expr:`const MySortedContainer&` - (or as text :cpp:texpr:`const MySortedContainer&`). - - .. versionadded:: 1.7 - The :rst:role:`cpp:expr` role. - - .. versionadded:: 1.8 - The :rst:role:`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. - -.. rst: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 \ - std::vector - - .. cpp:namespace:: template 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 \ - std::vector - - .. cpp:function:: std::size_t size() const - - or:: - - .. cpp:class:: template \ - std::vector - -.. rst:directive:: .. 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``. - - .. versionadded:: 1.4 - -.. rst:directive:: .. 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 - - .. versionadded:: 1.4 - -Info field lists -~~~~~~~~~~~~~~~~~ - -All the C++ directives for declaring entities support the following -info fields (see also :ref:`info-field-lists`): - -* ``tparam``: Description of a template parameter. - -The :rst:dir:`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. - -.. versionadded:: 4.3 - The ``retval`` field type. - -.. _cpp-roles: - -Cross-referencing -~~~~~~~~~~~~~~~~~ - -These roles link to the given declaration types: - -.. rst:role:: 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. - - .. versionadded:: 2.0 - The :rst:role:`cpp:struct` role as alias for the :rst:role:`cpp:class` - role. - -.. admonition:: Note on References with Templates Parameters/Arguments - - These roles follow the Sphinx :ref:`xref-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```. - 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\```. - - When a custom title is not needed it may be useful to use the roles for - inline expressions, :rst:role:`cpp:expr` and :rst:role:`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 :rst:role:`cpp:any` and :rst:role:`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: - -.. cpp:namespace-push:: overload_example -.. cpp:class:: C - - .. cpp:function:: void f(double d) const - .. cpp:function:: void f(double d) - .. cpp:function:: void f(int i) - .. cpp:function:: void f() - -References using the :rst:role:`cpp:func` role: - -- Arbitrary overload: ``C::f``, :cpp:func:`C::f` -- Also arbitrary overload: ``C::f()``, :cpp:func:`C::f()` -- Specific overload: ``void C::f()``, :cpp:func:`void C::f()` -- Specific overload: ``void C::f(int)``, :cpp:func:`void C::f(int)` -- Specific overload: ``void C::f(double)``, :cpp:func:`void C::f(double)` -- Specific overload: ``void C::f(double) const``, - :cpp:func:`void C::f(double) const` - -Note that the :confval:`add_function_parentheses` configuration variable -does not influence specific overload references. - -.. cpp:namespace-pop:: - - -Templated declarations -^^^^^^^^^^^^^^^^^^^^^^ - -Assume the following declarations. - -.. cpp:class:: Wrapper - - .. cpp:class:: template \ - Outer - - .. cpp:class:: template \ - Inner - -In general the reference must include the template parameter declarations, -and template arguments for the prefix of qualified names. For example: - -- ``template\ Wrapper::Outer`` - (:cpp:class:`template\ Wrapper::Outer`) -- ``template\ template\ Wrapper::Outer::Inner`` - (:cpp:class:`template\ template\ Wrapper::Outer::Inner`) - -Currently the lookup only succeed if the template parameter identifiers are -equal strings. That is, ``template\ 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`` - (:cpp:class:`Wrapper::Outer`) -- ``Wrapper::Outer::Inner`` - (:cpp:class:`Wrapper::Outer::Inner`) -- ``template\ Wrapper::Outer::Inner`` - (:cpp:class:`template\ Wrapper::Outer::Inner`) - -(Full) Template Specialisations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Assume the following declarations. - -.. cpp:class:: template \ - Outer - - .. cpp:class:: template \ - Inner - -.. cpp:class:: template<> \ - Outer - - .. cpp:class:: template \ - Inner - - .. cpp:class:: template<> \ - Inner - -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\`` (:cpp:class:`template\<> -Outer\`) and ``template\<> template\<> Outer\::Inner\`` -(:cpp:class:`template\<> template\<> Outer\::Inner\`). As a -shorthand the empty template parameter list can be omitted, e.g., -``Outer\`` (:cpp:class:`Outer\`) and ``Outer\::Inner\`` -(:cpp:class:`Outer\::Inner\`). - -Partial Template Specialisations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Assume the following declaration. - -.. cpp:class:: template \ - Outer - -References to partial specialisations must always include the template -parameter lists, e.g., ``template\ Outer\`` -(:cpp:class:`template\ Outer\`). Currently the lookup only -succeed if the template parameter identifiers are equal strings. - -Configuration Variables -~~~~~~~~~~~~~~~~~~~~~~~ - -See :ref:`cpp-config`. - .. _domains-std: The Standard Domain