cross-referencing overloaded function with cpp.apigen ext

[2bndy5]

I think this hasn't been developed yet, but I wanted to be sure it wasn't me. I'm migrating a project away from doxygen and a class has some overloaded functions:

/// @ingroup pinnacle-touch-api
class PinnacleTouch
{
    /// @id relative-report
    void read(RelativeReport* report);

    /// @id Absolute-report
    void read(AbsoluteReport* report);
};

In the documentation for the RelativeReport struct, I'd like to explicitly cross-link to PinnacleTouch::read(RelativeReport*), but IDK how. When I use

`PinnacleTouch::read(RelativeReport*)`

It renders a code span: which has links to

• the PinnacleTouch class because it is the parent scope of read()
• PinnacleTouch::read(AbsoluteReport*) because it is taking the first overload in alphabetical order.
• the RelativeReport struct as represented by the parameter's datatype.

Am I missing something? Do I need to use the USR as we haven't fully developed a way to specify specific entities in cpp.apigen ext?

[2bndy5]

I could use a reference to the generated doc name:

:doc:`PinnacleTouch.read[RelativeReport]-c4770235`

but this is not ideal...

[2bndy5]

I just realized my cpp_apigen_rst_prolog has the inline literal using :cpp:expr:. When I explicitly set it to

:cpp:func:`PinnacleTouch::read(RelativeReport*)`

I get a warning reminiscent of my days using doxygen+breathe:

\CirquePinnacle\docs\<cpp_apigen_rst_prolog>:-1: WARNING: Unparseable C++ cross-reference: 'PinnacleTouch::read(RelativeReport*)()'
Error in cross-reference.
If shorthand ref:
  Invalid C++ declaration: Expected end of definition. [error at 19]
    PinnacleTouch::read(RelativeReport*)()
    -------------------^
If full function ref:
  Error when parsing function declaration.
  If the function has no return type:
    Invalid C++ declaration: Expected end of definition or ;. [error at 36]
      PinnacleTouch::read(RelativeReport*)()
      ------------------------------------^
  If the function has a return type:
    Error in declarator
    If declarator-id with parameters-and-qualifiers:
      Invalid C++ declaration: Expected identifier in nested name. [error at 19]
        PinnacleTouch::read(RelativeReport*)()
        -------------------^
    If parenthesis in noptr-declarator:
      Error in declarator or parameters-and-qualifiers
      If pointer to member declarator:
        Invalid C++ declaration: Expected '::' in pointer to member (function). [error at 34]
          PinnacleTouch::read(RelativeReport*)()
          ----------------------------------^
      If declarator-id:
        Invalid C++ declaration: Expecting "(" in parameters-and-qualifiers. [error at 34]
          PinnacleTouch::read(RelativeReport*)()
          ----------------------------------^

And setting add_function_parentheses to False doesn't help.

[jbms]

I think maybe :cpp:func will work if you specify the return type as well so that it can parse properly.

As for supporting cross references based on the id directly --- I agree that could make sense, but since the C++ cross referencing support in the Sphinx C++ domain is already very complicated, we would need to consider carefully where to inject such support, or use a different role.

[2bndy5]

I also tried using the return type without success. It just renders as a literal block (& and doesn't output any errors/warnings).

:cpp:func:`void PinnacleTouch::read(RelativeReport*)`

Including the parameter name yields the same effect.

[2bndy5]

I agree that could make sense, but since the C++ cross referencing support in the Sphinx C++ domain is already very complicated, we would need to consider carefully where to inject such support, or use a different role.

I'm ok with a new role in the cpp domain for overloads. My first thought would be :cpp:overload:, but it isn't indicative of the apigen origin.

This problem is such a recurring pain in using breathe, so I think users would welcome an explicit workaround.