Generating API Documentation?

Preda asks: "I have been recently tasked with generating API documentation for new and legacy code. Given the amount of legacy code (in C, VB6, VB.NET, PHP, and other languages) and new code that needs to be documented, are there any easy auto generating API programs out there. I have done a few searches but nothing that I have found stood out as a 'use me' solution. Does anyone have any advice?"

Comments

doxygen, commentator

[Dioscorea]

I like doxygen for C++. It's modeled on javadoc and plots nice dependency and hierarchy graphs using graphviz.

Other than that, there's the Commentator...

Don't auto generate

[AuMatar]

Don't bother with autogeneration. First off- developers are far less likely to comment in wierd formats, or update comments in wierd formats (even when they do, its easy to typo and break the generator). You end up with out of date or missing documentation due to this. Secondly, for good documentation you need more than what an autogenerator can do anyway- good documentatition has examples, use cases, warnings and gotchas, etc. The old fashioned way is best- talk to the developers working on it, and write the documentation by hand.

Re:Don't auto generate

[Zebra_X]

That's just silly Leeeeeroyy. Would you have your team of 10 programmers also code in whatever style they please? Um - no? Standards are part of the development process from coding, db design and yes, even comments. It's not the developers choice to comment their code. They do it because they are told to do it, and it's their forking job. If they don't do it, ya FIAED. Plus any developer worth his salt comments when he has to work with other programmers. As far as comment formats - if you work with a decent IDE such as eclipse or VS.NET there are a couple de facto formats for comments out there. Code documentation and auto generation at an API level is very useful and it is simply one of a number of tools that you can use to maintain visibility into your code base. To say otherwise is well, just silly.

Commentator

[RAMMS EIN]

Commentator. Because you _know_ the coders haven't properly commented their code.

Web, Weave and Tangle

[samjam]

Use, web, weave and tangle, the famous tools behind Knuth's literate programming mindset.

Instead of writing code and not commenting it, you write a book on what you want your code to do, littered with examples of how it works and justifying why, and the tools somehow produces the C files and compile the library for you.

At least its something like that, the weave documentation didn't seem clear enough at the time for me to get it to do anything useful. *cough* I needed instructions not why's and because's

However it looks like folk are doing something useful with it: http://www.ox.compsoc.net/~gemini/simons/webperl/