C++ domain limited template support

[andreacassioli]

Hi,
I would like to write docs for a c++ function with this signature

.. cpp::function:: template<typename T, int N> namespace::function_name< T , N >(shape_t<N> shape, std::function<T(ptrdiff_t)> f)

but it is not recognized by the C++ domain. I got an error as

WARNING: Invalid definition: "," or ">" in template expected

Investigating it seems that the int params in template are not supported. Is there any plan for that?

[jakobandersen]

Currently the C++ domain does not support template declarations (see also issue #1314), but only template instantiations. As a temporary "solution" you can write
.. cpp:function:: namespace::funcction_name<T, N>(arg1, arg2)
and then change it back when template support is implemented.

[cbiffle]

FYI, the temporary "solution" does not work for operators.

[cbiffle]

Here are a few other cases I've encountered, for your consideration.

I'm writing my docs by hand, not using Breathe, in case you're curious. (Doxygen chokes harder on my templates than Sphinx does; as noted below, I can kind of make the current Sphinx implementation do what I want.)

Default template parameters

This works:

.. cpp:class:: Maybe<T, CheckPolicy>

This doesn't:

.. cpp:class:: Maybe<T, CheckPolicy = LaxCheckPolicy>

Which probably makes sense, since you're parsing the expression grammar and what I just wrote isn't legal. But currently there's no obvious way to specify default template parameters, except for this:

Template operators and template constructors

It isn't legal to pass template parameters to an operator, so currently there's no way of discussing a template operator, except to mention the types in passing without any explanation of where they came from (the S type in the screenshot):

Template constructors are in a similar boat -- you can't explicitly pass template arguments to a constructor -- but they get a pass in the current C++ domain implementation because it doesn't distinguish them from template functions:

Non-type template parameters

In an invocation there's no way to tell which parameters are types vs. non-types, and no way to indicate the type of non-type parameters. The convention I'm currently using is to lowercase the non-types and hope the reader gets it, but this doesn't give me a good way of indicating their type:

Partial specializations

I haven't even figured out how to express this one.