update exhale/breathe interface for doxygen{function,macro} (C++17 attributes cause failure)

[torbjoernk]

Using the C++17-introduced attributes to function parameters such as [[maybe_unused]] causes Doxygen/Exhale/Breathe/Sphinx to fail with error messages similar to:

Exception occurred:
  File "/usr/lib/python3.8/site-packages/sphinx/util/cfamily.py", line 291, in fail
    raise self._make_multi_error(errors, '')
sphinx.util.cfamily.DefinitionError: Invalid C++ declaration: Expected identifier in nested name. [error at 15]
  (double const, ] double const)
  ---------------^

with a function declaration/definition similar to

void foo(double const a, [[maybe_unused]] double const b)

[svenevs]

Oh no! Can you please share a self contained example I can build? Or zip up a folder after running make html?

There could be a few causes and it depends on what gets generated, doxygen output (and how I parse it) or breathe. Happy to take a look though!

[torbjoernk]

Thank you very much for the prompt response! 👍

Here you go with a minimal example: svenevs_exhale_106.zip

[opelx]

Please note that there are more attributes, see Attribute specifier sequence

[torbjoernk]

@svenevs Can I support you in the investigation and fix any further? Can you briefly list code locations related to the potential causes you had in mind?

[svenevs]

Sorry for the delay, thank you for demonstrating interest and sharing additional information. See linked issue comment for the relevant sections of the code (and also linked PRs). This is all ultimately the same issue in disguise, but no way for you the reporter to know this because it bubbles up differently over time.

Long term, I want to PR to breathe to ask them if we can enable every directive to have a bypass for refid lookup. So that we can e.g., .. doxygenfunction:: __refid__::{function_refid} or .. doxygenclass:: __refid__::{class_refid}. That way we don't need to know the rules, which would fix the longstanding template function overload problem. But that may be challenging to implement.

#98 (comment)

There are a lot of other things that break related to signatures that I think would be best fixed by updating the interface between exhale and breathe. It's this project's responsibility, since people using breathe without exhale don't have a need for this feature. If somebody wants to spearhead finding a way to allow exhale to specify a refid option to breathe function directives (rather than a signature and possible parameters), that would be extremely valuable for this project and its users and I'd be grateful 🙂

Edit: see the breathe directives, I think we need both doxygenfunction and doxygendefine (for macros)?

It will affect their "finder factory", but your reward would be glorious: the template function overloads and many other metaprogramming flaws exhale chokes on will disappear. That said, I haven't had time to look into it and it may be a big task worth postponing until I can be more actively involved later this summer. Note: the tests will break horribly, I'm definitely OK with merging PRs provided we have some user-tests (just build a few projects, we can always patch release over if big problems happen).

I'm going to update the title and pin this as the interface update meta-issue, but a hack may also be achievable to at least get them working in most cases ™️ ⁉️