Doxygen documentation need to be extended for deprecated methods in TTValue.h

[lossius]

In Core/Foundation/library/includes/TTValue.h quite a few methods are marked as being deprecated (declared as TT_DEPRECATED). IMHO the doxygen documentation for each of these should be extended with suggestions for what methods to use instead.

@Tim: Would you be able to take a look at this and extend the Doxygen documentation? I'll add this to the issue tracker as well when I get online as a high priority issue.

[tim]

@lossius No, sorry. I think you meant to ask @tap?

[lossius]

Sorry, @tim, I didn't realise that GitHub would pass comments this way on to people outside of the project. I of course meant @tap .

Cheers, Trond

[lossius]

Hi Nathan, based on @tap 's comment in dd552ab it sounds like you might be able to add documentation for the remaining deprecated function declarations in this file? Thanks!

[nwolek]

Yep, it's part of the milestone. I'll get to it eventually.

[nwolek]

I think because there are missing comments for some non-deprecated methods, Doxygen is getting confused. The solution appears to be making sure that the documentation is as complete as possible. This is not necessarily a bad thing.

[nwolek]

Getting Doxygen to see all the comments for TTValue functions is proving very tricky. I have tried reworking the syntax several ways, but many of the deprecated comments simply will not render into the HTML docs.

Another factor that may be contributing to this: TTValue is a subclass of the std C++ vector class. All the freebie functions that we get from this subclass are not documented in our project. This likely confuses Doxygen.

TTValue is such an important class that it needs to be properly documented, but I am growing tired of fighting Doxygen on this issue.

FYI - I am holding back from pushing a few of my latest commits because I don't have time to test first. Have to head to a meeting. I might get back to this later today.

[nwolek]

re last FYI - actually just made a new branch (issue/165) and pushed to origin in case @lossius or someone else wants to take a look

https://github.com/jamoma/JamomaCore/blob/issue/165/Foundation/library/includes/TTValue.h

[nwolek]

A possible solution when Doxygen doesn't see a function: http://stackoverflow.com/questions/10171737/how-to-change-function-description-in-derived-class-with-doxygen

[tap]

Whether you want to invent a macro (and define it in your Doxyfile) like the accepted answer, or just do the "ugly" thing in the original question, is up to you. I'm happy with either, FWIW.

best, Tim

On Thu, May 8, 2014 at 6:24 PM, nwolek notifications@github.com wrote:

A possible solution when Doxygen doesn't see a function:

http://stackoverflow.com/questions/10171737/how-to-change-function-description-in-derived-class-with-doxygen

— Reply to this email directly or view it on GitHubhttps://github.com/jamoma/JamomaCore/issues/165#issuecomment-42618422 .

[nwolek]

I believe I finally found a solution to the missed deprecation here: http://stackoverflow.com/questions/8044457/use-doxygen-to-document-a-function-that-is-sent-to-a-macro-c

Very similar to earlier link. We just need to tell Doxygen that it should preprocess certain MACROS before doing its work.