Original Post
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.
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.