Open 2bndy5 opened 1 year ago
I could use a reference to the generated doc name:
:doc:`PinnacleTouch.read[RelativeReport]-c4770235`
but this is not ideal...
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.
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.
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.
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.
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:
In the documentation for the
RelativeReport
struct, I'd like to explicitly cross-link toPinnacleTouch::read(RelativeReport*)
, but IDK how. When I useIt renders a code span: which has links to
PinnacleTouch
class because it is the parent scope ofread()
PinnacleTouch::read(AbsoluteReport*)
because it is taking the first overload in alphabetical order.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?