Code Documentation A better way?

[dexter 0]

This is not so much a question, actually, but a bit of a plug for an interesting tool I've discovered recently.

Anyway. How does everyone else document their code? Are in-source comments sufficient? Do you write extra detailed documentation outside of the code? Or do you generate external documentation from the code?

Since I've been doing Java recently, I was in awe when I discovered javadoc. An incredible tool that allows you to generate external documentation for your code from your comments in-source.

The syntax is reasonably simple, allowing the comments to be readable in and out of the source code.

And so, I set off in search for a similar tool for C/C++. And what do I find? Doxygen. Incredible. I've already gone through and re-commented some of my reasonably completed code to include this style of commenting. Fantastic results. Instead of text documents laid out the best I can, this tool can generate all the documentation from the code in a few different styles (HTML, LaTeX, man, etc.).

Mind you, doxygen can handle:

C++, C, Java, Objective-C, IDL (Corba and Microsoft flavors) and to some extent PHP, C#, and D

Support for more languages is on the way. Also, the code has been re-worked to make it easy for developers to add support for different languages.

I seriously am never going to write external documentation for my code ever again.

And an additional question to the ones I asked above, if you do generate the code with a tool similar tool to this, what tool do you use?

I'm done plugging. Off to go re-document some more code...

[osknockout 0]

Hello once again dexter.
In source comments should be sufficient. or you can always 'read the (expletive) manual' as Linus Torvalds used to say.

Actually there was a UNIX tool that did that did the same thing as your javadoc thingy way back, only reason I know because I look through my install packages for Linux. Of course it was just plain text, but how hard could it be to re-port it?

I seriously am never going to write external documentation for my code ever again.

Obviously you have never seen Freeciv code or you're crazy.
I'll find the tool someday... right now, I'm off and away.