Possible Feature : doxygen on headers rather than source?

[elliotwoods]

it seems that if the doxygen comments (which are really well made) were in the headers, then IDE's could use it to provide more assistance within the text editor

or maybe there's something i'm not seeing here? (if so please mark this as closed :)

[nemequ]

I don't know that any editors actually support that. VS seems to only support DocXml, though maybe that is only for C#. Have you tried copying over comments from the sources to the headers to see if it makes any difference?

I would think the prototype would be all the information you would need, especially if the parameter names are included. Presenting the full documentation seems like it would be way too much noise for the UI…

The comments are in the sources right now because it is easier to keep them up to date when they are there than in the headers, and I like to keep the headers small. If moving them to the headers provides a real benefit I'll consider moving them…

It seems like the "right" way to do this would be to have Doxygen generate DocXml which you could then load into VS, or have a tool which takes the intermediate XML representation used by doxygen and converts it to DocXml.

[elliotwoods]

By default we get:

Copying to header file like so:

/**
* @brief Get the plugin associated with a codec
*
* @param codec The codec
* @return The plugin to which the codec belongs
*/
SQUASH_API SquashPlugin*           squash_codec_get_plugin                   (SquashCodec* codec);

results in: which is imperfect, but for some functions can be useful for many users (e.g. for something like squash_codec_init it tells you the situations where you do and don't want to use that function). But I can see your points about keeping headers clean and editing documentation next to implementation (i.e. in c files).

Perhaps something to keep in mind, even if there's no momentum to switch over now.

The 'official windows route' would be .winmd files?

[nemequ]

I've been thinking about this, and I've decided to keep things as they are for now. Moving the documentation to the headers has a couple of advantages:

• Documentation is basically installed whenever the headers are.
• Some IDEs may be able to make use of this information, at least in an incomplete way.

However, there are also a couple disadvantages:

• Lots of additional bloat in the headers.
• Documentation lives further from the implementation.

That last point is really the deal-breaker. I've been involved with projects where the documentation lives in the headers, and it tends to make it harder to keep the documentation up to date. I'd rather have better documentation than have it be slightly more accessible for some users.

The 'official windows route' would be .winmd files?

That looks interesting. I hadn't heard of winmd files before. It's a bit difficult to find information on them, and AFAICT there is no official documentation on the format… I'd love to see a way to convert Doxygen comments to winmd files. Is there any way to generate winmd files other than using VS to extract DocXml comments?

[nemequ]

http://www.codeproject.com/Articles/476957/WINMDplusFilesplusUnderplustheplusHood is the best documentation I've been able to find. Apparently winmd files are "… DLL files (or CLR assemblies) with rich .Net framework metadata to expose underlying Windows operating system APIs."

Without documentation it's probably not going to be feasible to generate them, and even with documentation it would be a pretty big project, at least if we stick with Doxygen (which I'm not overly attached to, it's merely less bad than the other solutions I've tried).

I'm going to close this issue, but if you have any other ideas for better VS support please file another issue. I'm definitely interested in improving Squash's support for IDEs, it's just moving the documentation away from the implementation is a bit hard to swallow.

[elliotwoods]

For possible future use I've added a question on Stack Overflow for moving comments from source to headers on build install (i couldn't find any existing informaiton about this) http://stackoverflow.com/questions/35356241/automatically-copying-doxygen-comments-from-source-to-headers-c-c

[nemequ]

Interesting idea. AFAIK there is no way to get SO to notify me of an answer (maybe the fact that I added a comment will do the trick, but I don't think so) so please let me know if anyone provides a good answer.