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

Wiki?

[Bastian]

With so many languages, I'm not sure there's any one solution that can handle all of them. And if you want good, readable documentation, you're going to have to be describing all of the functions, objects, constants, etc. in human-written prose anyway.

Why not cut down on the workload for you by setting up a documentation wiki and asking the development team to help?

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.

Re:Don't auto generate

[dubl-u]

I agree with you completely that programmers should write code that communicates intention well. But I disagree with this:

Plus any developer worth his salt comments when he has to work with other programmers.

I used to think so, but now I'm doing full unit testing, refactoring, and pair programming. I now think comments are the second-worst place for information about the code, (followed only by external documentation).

The best choice is to write code that's clear: short methods, clear variable names, extracting long expressions as variables to convey meaning, and extracting long blocks as clearly named methods. It helps to make good use of language constructs (e.g., private, protected, final). And of course, you should break the system into discrete objects of moderate size and packages of reasonable collections of objects.

Then the next best place for info is in the unit tests. The unit tests are a great place to explain how to use something and what the interesting edge cases are. Unlike other documentation, the computer can verify the unit tests to make sure they're always up to date.

Only if I can't find a way to express it in those do I write comments. My (and my team's) comments these days are mainly limited to a short explanation for some classes, an explation of some weirdness forced on us by an externality (e.g., "See JDK bug 510431"), or the occasional TODO comment. I doubt if our comment LOC ratio is above 1% of total code.

If I'm writing a library for public consumption, I'd use the magic documentation generation for anything that's part of the API. But for internal code? Not anymore.

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/