Sign in to follow this  
Yann L

Doxygen is driving me insane

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
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
doxygen does give you some ability to customize the output. From the doxygen docs:

Since version 1.2.18, Doxygen can generate a new output format we have called the "Perl Module output format". It has been designed as an intermediate format that can be used to generate new and customized output without having to modify the Doxygen source. Therefore, its purpose is similar to the XML output format that can be also generated by Doxygen. The XML output format is more standard, but the Perl Module output format is possibly simpler and easier to use.

Share this post


Link to post
Share on other sites
Actually, the idea with XSLT is interesting - since doxygen can generate preparsed XML, I should be able to create some nice HTML styles through XSLT and possibly some further postprocessing. I have to look into that.

Thanks for the suggestions everybody. At least I now see a workable alternative approach, I'll have to see how we can minimize the efforts required. I'd really like to get professional level source code documentation using an OSS approach, beyond doxygen & co. Heh, what a perfect opportunity to delegate some annoying XML work to another team member [grin]

Share this post


Link to post
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now

Sign in to follow this