mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
761 lines
22 KiB
ReStructuredText
761 lines
22 KiB
ReStructuredText
.. highlight:: rst
|
|
|
|
==============
|
|
The C++ Domain
|
|
==============
|
|
|
|
.. versionadded:: 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``).
|
|
|
|
.. 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<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>
|
|
|
|
.. 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<typename U> \
|
|
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<class T> \
|
|
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<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.
|
|
|
|
.. cpp:type:: std::vector<int> 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<int, std::string>
|
|
:no-contents-entry:
|
|
:no-index-entry:
|
|
|
|
Declaration of a type alias.
|
|
|
|
.. cpp:type:: template<typename T> \
|
|
MyContainer = std::vector<T>
|
|
: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<MySpecificEnum>::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<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:
|
|
|
|
.. cpp:concept:: template<typename It> std::Iterator
|
|
:no-contents-entry:
|
|
:no-index-entry:
|
|
|
|
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<int>&`
|
|
(or as text :cpp:texpr:`const MySortedContainer<int>&`).
|
|
|
|
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<int>&`
|
|
(or as text :cpp:texpr:`const MySortedContainer<int>&`).
|
|
|
|
.. 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<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
|
|
|
|
.. 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-xref-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<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, :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
|
|
:no-contents-entry:
|
|
:no-index-entry:
|
|
|
|
.. cpp:function:: void f(double d) const
|
|
:no-contents-entry:
|
|
:no-index-entry:
|
|
.. cpp:function:: void f(double d)
|
|
:no-contents-entry:
|
|
:no-index-entry:
|
|
.. cpp:function:: void f(int i)
|
|
:no-contents-entry:
|
|
:no-index-entry:
|
|
.. cpp:function:: void f()
|
|
:no-contents-entry:
|
|
:no-index-entry:
|
|
|
|
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
|
|
:no-contents-entry:
|
|
:no-index-entry:
|
|
|
|
.. cpp:class:: template<typename TOuter> \
|
|
Outer
|
|
:no-contents-entry:
|
|
:no-index-entry:
|
|
|
|
.. cpp:class:: template<typename TInner> \
|
|
Inner
|
|
:no-contents-entry:
|
|
:no-index-entry:
|
|
|
|
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``
|
|
(:cpp:class:`template\<typename TOuter> Wrapper::Outer`)
|
|
- ``template\<typename TOuter> template\<typename TInner> Wrapper::Outer<TOuter>::Inner``
|
|
(:cpp:class:`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``
|
|
(:cpp:class:`Wrapper::Outer`)
|
|
- ``Wrapper::Outer::Inner``
|
|
(:cpp:class:`Wrapper::Outer::Inner`)
|
|
- ``template\<typename TInner> Wrapper::Outer::Inner``
|
|
(:cpp:class:`template\<typename TInner> Wrapper::Outer::Inner`)
|
|
|
|
(Full) Template Specialisations
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Assume the following declarations.
|
|
|
|
.. cpp:class:: template<typename TOuter> \
|
|
Outer
|
|
:no-contents-entry:
|
|
:no-index-entry:
|
|
|
|
.. cpp:class:: template<typename TInner> \
|
|
Inner
|
|
:no-contents-entry:
|
|
:no-index-entry:
|
|
|
|
.. cpp:class:: template<> \
|
|
Outer<int>
|
|
:no-contents-entry:
|
|
:no-index-entry:
|
|
|
|
.. cpp:class:: template<typename TInner> \
|
|
Inner
|
|
:no-contents-entry:
|
|
:no-index-entry:
|
|
|
|
.. cpp:class:: template<> \
|
|
Inner<bool>
|
|
:no-contents-entry:
|
|
:no-index-entry:
|
|
|
|
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>`` (:cpp:class:`template\<>
|
|
Outer\<int>`) and ``template\<> template\<> Outer\<int>::Inner\<bool>``
|
|
(:cpp:class:`template\<> template\<> Outer\<int>::Inner\<bool>`). As a
|
|
shorthand the empty template parameter list can be omitted, e.g.,
|
|
``Outer\<int>`` (:cpp:class:`Outer\<int>`) and ``Outer\<int>::Inner\<bool>``
|
|
(:cpp:class:`Outer\<int>::Inner\<bool>`).
|
|
|
|
Partial Template Specialisations
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Assume the following declaration.
|
|
|
|
.. cpp:class:: template<typename T> \
|
|
Outer<T*>
|
|
:no-contents-entry:
|
|
:no-index-entry:
|
|
|
|
References to partial specialisations must always include the template
|
|
parameter lists, e.g., ``template\<typename T> Outer\<T*>``
|
|
(:cpp:class:`template\<typename T> Outer\<T*>`). Currently the lookup only
|
|
succeed if the template parameter identifiers are equal strings.
|
|
|
|
Configuration Variables
|
|
-----------------------
|
|
|
|
See :ref:`cpp-config`.
|