WYSIWYG in Doxygen

Question

I'm working on a fairly large project written in C. The idea was to build a library of modular blocks that can be reused across several platforms. Each module is associated with a word document in .docx format (huge pain to diff-merge). In these docs, an interface section is specified, listing datatypes and publicly accessible functions. These were often inconsistent with the actual implementation in code, and wading through all this documentation was a pain.

I've been working to switch to doxygen to simplify document management. I haven't found a good way to embed the previously written documentation into the doxygen output. I've copy-pasted them into sections and used modules to group the sources together, but the document sections look ugly in the comments (the output is pretty) and since doxygen takes a while to parse through our code (about 30 mins), validating formatting is a pain.

Is there some way to WYSIWYG large blocks of documentation into doxygen? I feel this would improve the number of people documenting their code, and the quality of that documentation. I considered linking to html, but that splits out the documentation. I also considered putting them inline in html, but this also seems like a pain and would mean everyone needs a WYSIWYG HTML editor (or some html skillz).

Any ideas on how to make things easier and prettier?

Thanks loads.

Answer 1

I suggest printing the word documents in HTML. Doxygen can include HTML documents or at a minimum, can accept HTML syntax in comments and descriptions.

Answer 2

You can put <pre> ... </pre> sections in your comments and by manipulating a little bit the .css you can format it to your liking.

Answer 3

My add-in, AtomineerUtils may help.

It doesn't (yet) offer wysiwyg, but it does help with the day to day management and updating of Doxygen or DocXML documentation comments, which helps to keep them in sync with the code and tidy/readable with minimal effort - this usually results in programmers actually documenting stuff because the hassle factor is minimised.

So, sorry it's not a direct solution to your problem - but it may help you to get your team working better and more efficiently with embedded doxygen comments.