doxygen: documenting macros properly

[tap]

We have macros and in some cases they even have doxygen comments :-) For example, TT_NO_DEPRECATION_WARNINGS in TTBase.h.

The documentation for this does not show up in Xcode's documentation pane though which leads me to believe that we need some magic. Do you know what that magic is?

[nwolek]

Well the MACROs show up online here: http://api.jamoma.org/group__macros.html

the tag needed in your macro comments is "@ingroup macros"

But I am not sure this will help it to show up in Xcode

[nwolek]

This is proving difficult for me to test, as my copy of Xcode doesn't seem to want to display any hints (even the ones I know are there). Did you have to do some thing to enable it @tap?

I did find this in my searching. It appears Doxygen can build a Docset for Xcode. This might be a way to span the different projects in Core: http://www.stack.nl/~dimitri/doxygen/manual/config.html#cfg_generate_docset

[nwolek]

Just ran this and it generates that 165 MB file that Xcode seems unable to decipher. If we could get this working, it would be quite nice. Sorry if this is a bit of digression.

Back to the original question: Since macros are system wide, they are documented outside the class. That is why we add them to a macro group. You can see the syntax here: https://github.com/jamoma/JamomaCore/blob/master/Foundation/library/includes/TTMatrix.h#L264

[nwolek]

Added section on adding Macros to Doxygen group here: https://github.com/jamoma/Jamoma/blob/dev/Doxygen/intro_chapters/C-StyleGuide.dox#L156

Part of resolving this issue on umbrella: https://github.com/jamoma/Jamoma/issues/122

Does that also close this issue?

[nwolek]

This issue migrated from talking about macros to making the Doxygen comments display in Xcode. Since our work on jamoma2 seems to have positive results toward this goal, I am closing the issue here.