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

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

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.

Doxygen is not an answer yet

[abelikoff]

I've been using Doxygen for several years already and while it is a great tool that simplifies documentation generation a lot, the output is far from perfect by any reasonable standards:

• Consider .NET Development Center. MSDN has been following this documentation presentation model for years and it proved to be quite convenient for developers. You get a hierarchical API tree on the left and documentation on the right. The documentation for API groups is clumped together with nice introductory articles etc. Unfortunately it is practically impossible to generate using Doxygen.
• Doxygen is not scalable. Period. If your source base is 10 million LOC and you change one function in one tiny file, you will have to run Doxygen on your entire source base to incorporate the change.
• Neither is Doxygen geared toward generating API manuals. This is actually the worst problem with the whole situation. I've seen projects, where people would generate Doxygen style API reference and call it "documentation." Well, just having a huge list of documented function is not documentation.

Having said that, I still think that Doxygen is the best automated documentation generator out there and I hope it'll answer all those issues in the future.

Re:Wiki?

[ivanwillsau]

Would any one be interested in developing a documentation wiki that integerates with something like doxygen? This is something that I have been thinking about doing my self.