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

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?

Standardized output

[Marxist Hacker 42]

MZ Tools for Visual Studio makes nice XML documentation in a large number of languages- then you only need an XSL transform to output it to a web page. I'm sure there's something similar out there for PHP- though it seems to me PHP's only real API is the CGI interface itself, which leaves you with only one interface per script.

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.

Re:Don't auto generate

[kbielefe]

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.

Creating the kind of code you describe is more of an art than a science. How short is too short? How long is too long? What is the difference between a clear name and an unclear one? Where is the best place to make a split?

Like art, most programmers know good code when they see it. Only some programmers can easily describe why the code is good in terms like the above. Even fewer have an instinct for creating beautiful code.

If you are fortunate enough to work on a small, hand-picked team of talented programmers, I envy you. Most departments tend to spread the talent around to give the most overall benefit. In order for a team to be effective, the least talented programmer on the team needs to be able to maintain code written by the most talented, and vice-versa. The coding standards should reflect that. A truly great programmer always keeps the skill level of his or her current and future colleagues in mind.

nDoc for all things .net

[RingDev]

check out a tool called nDoc. It can take the /// documentation auto generated in C# (in VS 2k3), or with VBCommentor (a plug in for VB/ASP.Net 2k2 and 2k3) and build it into CHM/HTML/MSDN help files.

Its nice since the /// auto documentation is built into the VS.Net IDE. I managed to talk my manager into encorporating it. And we have about 75% of our library documented in API style (class definitions and descriptions, function definitions, parameters, thread saftey, namespaces, the whole gambit.) The remaining 25% is under redesign so its documentation is still in limbo. But with VBCommentor/C# /// going back to document namespaces/classes/methods/members is a brease.

-Rick

Do you really want to suceed at this?

[EraserMouseMan]

I have been recently tasked with generating API documentation for new and legacy code.

This is usually what a company asks an important developer to do before they let him/her go. I hope this isn't your situation though. Hopefully they are promoting you to manager and letting you hire/train new employees (using your documented code).

Commentator

[RAMMS EIN]

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

Doxygen is good

[kherr]

Doxygen handles many languages, not just C++. It's a great utility and can produce some very complete "books" with introductions and full explanations. It will output in multiple formats. For the code you just add simple javadoc-style comments such as:

/**
* This is a function that does something.
*
* @param foo first argument
* @param bar second argument
*
* @return some useful value
*/


The comments have minimal markup, inside the code source, so when you edit the actual functions you can also read (and update) the comments.

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/

Doxygen, gtk-doc, vbdox, ...

[Raphael]

Doxygen is a good tool for many languages. It works best for C++, but it also has some limited support for PHP, which is in your list of requirements. There is also a fork of Doxygen called DoxyS. It generates prettier output for C++ but may not support the other languages as well as Doxygen. Another tool inspired by Javadoc is PHPDoc for PHP code. However, it does not seem to be actively developed anymore.

For plain C code, I prefer gtk-doc, which generates better output than Doxygen (IMHO, and for C only). You can see an example of the gtk-doc output by browsing the GTK+ API documentation.

Since you also mention Visual Basic, you could have a look at VBDOX. I haven't tried it myself so I don't know if it works well. There are some screenshots on their site, so maybe you should have a look and decide if you like the results.