Jump to content
  • Advertisement
Sign in to follow this  
Yann L

Doxygen is driving me insane

This topic is 5053 days old which is more than the 365 day threshold we allow for new replies. Please post a new topic.

If you intended to correct an error in the post then please contact us.

Recommended Posts

I've always been using a proprietary inhouse source documentation tool, but since I'm currently on some open source project, I need to use an OSS source doc system as well. Of course, doxygen came to mind. OK, I don't like it. Either my mind is not compatible with the usage concept of this program, or doxygen is far less flexible than it is supposed to be. First off, I'd like to keep the number of doxygen comments in my code down to an absolute minimum. I find them highly intrusive, and they clutter up my code. An exception are either the standard JavaDoc headers, or the triple slash ('/// Comment') comments. Those are OK, and admittedly work pretty well. But they aren't enough to get access to the more advanced features of doxygen. So I decided to separate the doxygen comments from the rest of the source in a separate file, as described in section 3.3 of the doxygen manual. But it seems I can't get all required functionality by deferring it that way. I also encounter some problems customizing the HTML formating doxygen produces. This is what I want (I needed to manually modify the generated HTML in order to get that): OK, by modifying the CSS, I could get the spacing right, and play with the fonts and colours. But as you can see in the image, I want the brief method description to be placed right beside the method itself. I could make doxygen put the description above or below, but not beside the method. I went through the doc many times, but just couldn't find anything. I must have missed something somewhere. Also, I'd like to have the class methods grouped together by functionality: all ctors, all arithmetic operators, compare operators, etc. I know I can do that with "//@{" and "//@}" tags within my class, but those tags are so extremely ugly, I don't want to see them all over my source. I couldn't find a way to defer that functionality to a separate documentation file. Is that possible ? I could defer the method description, but not the grouping ! Weird. I am this close to modify doxygen itself to suit my needs. But I just can't believe that such basic functionality as I described above isn't supported by the original unmodified application. Any help would be greatly appreciated ! PS: I forgot. Look at the image above. Why is it, that the there is a space between the operator keyword and the '*=' token, yet there is no such space between all others ? In my source, there is a space everywhere.

Share this post


Link to post
Share on other sites
Advertisement
I can't really help you with the spacing, but if you want nicer tags and more customizable output you can use NaturalDocs. Sorry to post a "don't use IE/Windows use Mozilla/Linux" type post, but my experience with Doxygen frustrated me. Redoing all your documentation from Doxygen to NaturalDocs isn't much fun, so you're probably looking for a better solution, I just thought I'd chime in since many people don't know about NaturalDocs, but most I've shown have liked it better.

Share this post


Link to post
Share on other sites
Quote:
Original post by Yann L
OK, I don't like it.

Amen. Can't help you with your question but if you can still switch to a different tool, consider using MonoDoc. I hate Doxygen with passion. I hate the way it works. I hate the way their documents look (they couldn't come up with better defaults?) I hate using it and I hate using the documents generated by it. Did I mention I hate Doxygen?

Share this post


Link to post
Share on other sites
cozman, Coffeemug, thanks for the alternative suggestions. I'm definitely open for that. A part of the codebase (the part not written by me, I may mention) is unfortunately doxygenified, so I thought about keeping that tool - but I already wasted so much time on this thing, and I can't seem to even remotely get the results I want.

I will definitely look into those alternative tools.

Share this post


Link to post
Share on other sites
For complete customized output in NaturalDoc you'll need some Perl, CSS hacking can produce some very nice results, but writing a new output module requires you to write some templates and some Perl to do the actual generation.

Share this post


Link to post
Share on other sites
Quote:
Original post by cozman
For complete customized output in NaturalDoc you'll need some Perl, CSS hacking can produce some very nice results, but writing a new output module requires you to write some templates and some Perl to do the actual generation.

Well, NaturalDoc doesn't look too bad, but it only offers full support for C# and Perl. The basic fallback C++ support is not sufficient for our application. Thanks for the suggestion anyway.

Share this post


Link to post
Share on other sites
Sorry, I forgot to mention that, the native language support is relatively new, I haven't seen it in action yet, but I hear C++ support is coming soon. Of course "soon" won't help you in your problem.

Share this post


Link to post
Share on other sites
You could always write you're own documentation-maker. It honostly doesn't sound too hard as long as you're not looking for fancy dynamically generated graphics and stuff.

Share this post


Link to post
Share on other sites
You could use the GCC-XML thingamabob to generate XML output of your code, and then run that through some XSLT or something similar.

You might have to run a separate pre-processing phase to grab the special tags...

but then you'd have to figure out how to associate the two..


ugh...

that might get ugly :-\

Share this post


Link to post
Share on other sites
Sign in to follow this  

  • Advertisement
×

Important Information

By using GameDev.net, you agree to our community Guidelines, Terms of Use, and Privacy Policy.

Participate in the game development conversation and more when you create an account on GameDev.net!

Sign me up!