Remove template walls

[geky]

Description

By selectively removing doxygen comments, we can present only the useful function documentation to users. Note that in C++11 these would just be vararg functions.

Still included are a single overload for functions + args, member function + args, and function + state + args.

In:

• EventQueue.h
  • call
  • call_in
  • call_every
  • event
• Event
  • constructor
• Callback
  • constructor
  • attach
  • callback

cc @AnotherButler, @pan-, @kegilbert

Pull request type

[ ] Fix
[x] Refactor
[ ] New target
[ ] Feature
[ ] Breaking change

[pan-]

What's the impact on doxygen rendering ?

[geky]

@pan- I'm struggling on how to show it before the CI runs, but we should now only see one set of function overloads instead of every set of overloads for each parameter list:

From:

To:

[pan-]

A better option would be to have a single documentation with varargs for doxygen:

#if defined(DOXYGEN_ONLY)

// single signature and documentation

#else 

// regular code

#endif

It would clean the output and avoid error from the CI jobs that test there is no warnings in the doc.

[geky]

Oh I see, we could do that too, although it would clutter the header file.

I'm not sure it's needed, the CI errors were about a misnamed parameter.

[pan-]

I got no strong opinion on this; the advantage is the possibility to use variadic templates syntaxe for the documentation. It may make the intent clearer rather than having the function with the most overloads.

[geky]

Oh! I understand now. That makes sense, let's see what that looks like.

[cmonr]

@geky Making a note here that this is still open.

[cmonr]

Closing this since no update has occurred in two weeks.

Feel free to reopen once an update is available.

[AnotherButler]

@geky Please update this. This was requested externally.

[geky]

Currently working on it on the branch outside of this pr, will reopen when ready for review