Doxygen makes me nauseous. At the moment I write plain C++ comments without any formatting when I get to choose, but I was thinking about POD as an alternative. You'd have to avoid putting "=" at the beginning of lines, but that never occurs in my code. A system that has C++ probably has Perl, and anyway it's fairly readable.

What do you think? Stupid idea?

Hejsan
get used to doxygen, its more or less 'standard' and no that hard to learn and use and its worth to use because it is reusable knowledge.
also, it has often good tool support, like generating the default tags
if you want to write more than just the minumum/default code comments, it also has some markdown support.
and if you want others to work with your code, do not come up with something 'special'
I am sure there are more reasons, but this should be enough.

what are your special problems with doxygen?

Väl mött!

I know how to use it but I think the generated man pages are inferior. The ones generated by perldoc are great and don't require a configuration file. Just `perldoc <file>`. The HTML generated by doxygen (and Javadoc nowadays -- the old Javadoc was better) is hard to read with text browsers. Probably relies heavily on CSS. It feels so bloated, like there should be a simpler way to do it. POD feels more elegant but is unfortunately non-standard, as you say.

The markdown support is great though.

I tried to give it another chance based on your advice, but I can't bring myself to do it. These are my problems with it, specifically:

• >2000 line configuration file generated by `doxygen -g`. Most lines are comments but still! Way too many options, and no options to disable the following behavior:
• The generated HTML uses JavaScript and lots of trash files. Awful to use with Lynx; must start X and install Firefox to read the documentation without barfing.
• The generated groff man pages are atrocious and there is no way to change them. For example there is nothing like `pod2man --center <text> --release <text>`. Why have man page support at all when it's so poorly implemented?
• All generated documentation contains advertisement for Doxygen (even in the man pages!), which can't be removed.

No, just no. I got over the configuration file and thought OK, as long as the HTML is good. But it isn't. So never mind the HTML, as long as the man pages are good. But they aren't. There is absolutely nothing good about it. Sure, I'll use it when I get paid for it and don't care about the project, but never voluntarily.

Am I the only one who doesn't like Doxygen? How can you put up with it? Do you reluctantly use it because everyone else uses it or do you genuinely like it? What do you see in it?

POD it is for me.

if you look at the projects that use doxygen,
http://www.stack.nl/~dimitri/doxygen/projects.html
and this list is not nearly complete
it can not be that bad, a lot of them come also with man pages that work excellent.
so possible the problem is that you are not used to doxygen but to something else and search therefore reasons to not like it.