C++, allow the creation of link anchors to deal with namespaces in parameters' types

[mquinson]

Problem description

When I describe a class or struct with .. cpp:class:: I like to give the full namespace qualification. But when I use this class as a parameter type in .. cpp:function:: or as type in .. cpp:var::, I prefer to keep it clear and lightweighted. As a result, the links from the parameters to their types are broken.

My logs are full of such error message:

docstring of simgrid::s4u::VirtualMachine::on_resume:1: WARNING: cpp:identifier reference target not found: xbt::signal<void(VirtualMachine const&)>

(Here, the problem seems to come from the fact that the xbt::signal template is used on the partially qualified VirtualMachine type name while the documented name is the full simgrid::s4u::VirtualMachine)

Solution I'd like
Since I'm using the cpp domain almost directly, I'd like to have a manual solution at hand, such as a .. cpp:anchor or something that would allow me to write something as follows:

.. cpp:anchor:: VirtualMachine

   (no parameter nor content here)

.. cpp:class:: simgrid::s4u::VirtualMachine

   (class description here)

.. cpp:var:: xbt::signal< void(VirtualMachine const  &)> simgrid::s4u::VirtualMachine::on_resume

   (variable description here)

Alternative I've considered

I've considered qualifying all types in parameters and such, but this leads to very heavy rendering in the doc. I think that this greatly hinders the doc readability.

Additional context

• My project is https://simgrid.org.
• The online documentation is here: https://simgrid.frama.io/doc/latest/app_s4u.html#api-reference
• It's built in the CI of the https://framagit.org/simgrid/simgrid project
• I'm using a set of sphinx extension of my own to extract the doc from Doxygen, but I don't think it's related here.

[jakobandersen]

In a sense this already can be done via the type directive:

.. cpp:type:: VirtualMachine = simgrid::s4u::VirtualMachine

(or simgrid::s4u::VirtualMachine VirtualMachine if you prefer/need pre-C++11 typdefs).
This will of course explicitly render the name trickery, which I guess is not too bad anyway. If the type alias is actually in the code, great, otherwise it may be a good opportunity to explain that it is only a documentation construct to make names appear more concise.

[mquinson]

Thanks for your quick answer, this is indeed a good improvement.

I'd prefer to not see these type aliases in my documentation, even more because they are not declared in the exported header files. The problem only occurs because I'm within a namespace {...} block.

Maybe what I'm looking for is a :anchor-only: parameter to the cpp:type::, to only output the anchor but not the visible display of the type? I cannot find of any good parameter name for this, sorry.

[mquinson]

what about the following?

.. cpp:type:: VirtualMachine = simgrid::s4u::VirtualMachine
   :visible: no