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?"

doxygen, commentator

[Dioscorea]

I like doxygen [stack.nl] for C++. It's modeled on javadoc [sun.com] and plots nice dependency and hierarchy graphs using graphviz [att.com].

Other than that, there's the Commentator [cenqua.com]...

Re:doxygen, commentator

[matheny]

I second doxygen. It supports nearly all the languages you need, a wide variety of commenting styles and with graphviz in the worst case at least you get a dependency tree. I've used doxygen for many years with a lot of success.

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.

Re:doxygen, commentator

[eraserewind]

Doxygen is nice, but it doesn't scale. It doesn't keep good track of what it has already done (at all?) and OOMs on large projects.

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?

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.

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

[Zugot]

Does this really work?

Is it too hard to put a javadoc tag in the comment, or a maybe even a pod tag?

Re:Don't auto generate

[SillyNickName4me]

Few humans can do this commenting in a specific style without making mistakes on the way, even more so if they do not have to deal with the consequences themselves directly.

Re:Don't auto generate

[rice_web]

I have to agree. But while hand-documentation is great, developer styling can retard the effectiveness of the notes in the documentation. When auto-generators that automatically create documentation and that read already-existing documentation that adheres to a certain pattern, you have the best of both worlds, for then you also bind your developers to a certain style.

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, extrac

Re:Don't auto generate

[Zebra_X]

I agree. I'm not saying that you should comment the hell out of things, just that along with writing clear consistent code (after all, it's what is doing the work) it's important to say what a method, function or object is for, especially if it is not toatally obvious. In the end the code should "speak for itself" but when someone doesn't have the source... well you need to be moderately descriptive.

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.

Re:Don't auto generate

[dubl-u]

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.

Which is part of wy I'm so big on pair programming. Few people are good enough to articulate why the length of a method is right, but if you're continously pairing with

Re:Don't auto generate

[geekoid]

"How short is too short? "
Readability. If it can't be read easily, then it is too short

"How long is too long?"

the moment is does more then one task.

"What is the difference between a clear name and an unclear one? "
I should be able to read a variable and know why it is there.

Coding is not art, it is engineering.
Good in engineering can have beauty, but that is not the same as art.

Art is created for the art. To create code with the idea that you are creating art is folly, and subject to 'mood coding'

Re:Don't auto generate

[Hard_Code]

Documentation is required when you can't write that mythical short-clear-obvious-intent code that is understood by everybody, including yourself one year from now. That actually happens to be most of the time. So yeah, documentation is pretty much required.

Re:Don't auto generate

[AuMatar]

Counting on unit tests to give documentation is a bad idea. Documentation tells us how code is supposed to work, both on an API level and internally. Unit tests fail this in a number of ways- they don't document internal workings, they don't document side effects at all (major problem), and they don't cover all cases (sure, you might think they do, but in reality they never quite do). They leave all types of corner cases completely undocumented. If you have to reverse engineer what code is supposed to

Re:Don't auto generate

[dubl-u]

Documentation tells us how code is supposed to work, both on an API level and internally. Unit tests fail this in a number of ways- they don't document internal workings, they don't document side effects at all (major problem), and they don't cover all cases (sure, you might think they do, but in reality they never quite do)

Unit tests should also tell you how code is supposed to work. Perhaps you need clearer unit tests. Think of them as executable documentation.

If the internal workings are so complicated t

Re:Don't auto generate

[AuMatar]

No, tests don't say how your code is supposed to work. They say the expected results for certain limited cases. This is nowhere near as clear as an actual prose description. Its also very dependant on the unit tests themselves not having bugs- and thats pretty rare. I count on a textual abstract description being accurate as far more likely than test code in my experience.

Internal workings *always* need explaining. Maybe not to you, but to the next guy to work on the code. Not leaving that explanatio

Re:Don't auto generate

[dubl-u]

No, tests don't say how your code is supposed to work. They say the expected results for certain limited cases. This is nowhere near as clear as an actual prose description. Its also very dependant on the unit tests themselves not having bugs- and thats pretty rare. I count on a textual abstract description being accurate as far more likely than test code in my experience.

It sounds to me like you've never encountered very good unit tests. Try doing test-driven development [agiledata.org] for a couple of months and you may

Re:Don't auto generate

[AuMatar]

No, it seems like you're either in programming Nirvana, or more likely, just haven't started running into problems yet. I'm not syaing unit tests are bad (they're good for testing). I'm saying they suck for documentation, and relying on them for documentation is setting yourself for big problems when you start to get developer turnover.

Re:Don't auto generate

[dubl-u]

It must be the former. I've been doing it this way for four or so years now and it seems to be working pretty well. In July we handed a codebase off to a team in another country, and allocated time during the transition to write any documentation they wanted. They had no interest in the kind of class-internal documentation you mentioned, and I've heard no complaints or questions since that would indicate the lack.

Really, until you try TDD, you'll never get how unit tests can accomplish the things I'm talkin

Re:Don't auto generate

[AuMatar]

Oh, I've done test driven development before. Testing is good for improving code quality. I love testing, especially if you have a good test department as backup. Its a bad way to document code, and a worse way to design code. I've had several situations where I've had to design standards compliant code where standards compliance meant I had to pass a qualification test. Generally, for every bug the test showed, we found 3 bugs in the tests themselves. Thankfully, we had real documentation to fall bac

Re:Don't auto generate

[AuMatar]

Actually yes, I would. Style guides are about the stupidest fucking thing you can do. Who cares what line the { is on, or wether the first letter in a variable name is a capital or not. It gives absolutely no benefit. It does, however, waste a shit ton of developer mind cycles to keep in the guidelines. And it makes code reviews an absolute waste of time- whenever I've had a review at a place with style guides it becomes "oh, you didn't follow obbscure guideline 132 here" rather than actually reviewing

Re:Don't auto generate

[Zebra_X]

AuMatar,

This, is why you are incorrect.

http://online.wsj.com/article/0,,SB112743680328349 448,00.html?mod=todays_us_page_one [wsj.com]

Philosophies such as yours don't scale. Period.

Re:Don't auto generate

[AuMatar]

And forcing people to put the brackets on one line instead of another will make everything automagicly better? Adding in some automatic doc grabbers that will provide crappy documentation will?

No, they won't. I know people who work at MS- from talking to them the problems are far deeper. It has to do with a very old, poorly designed code base that just had layers of cruft added on. Its a problem at a different level than what we're discussing.

Tools don't make up for good solid design. Nothing does. Th

Re:Don't auto generate

[Zebra_X]

You might have missed my point entirely. It's not just about brackets. When I talk about standards I mean that there should be a consistant agreed upon way of approaching code, line by line, class, interface, module, and subsystem construction. Consistancy is vitally important to the success and longevity of applications. It's also about readablity - consistancy of the code base from method structure to the way that methods, classes and events are used. There should be an agreed upon method for all of these

Re:Don't auto generate

[slamb]

First off- developers are far less likely to comment in wierd formats, or update comments in wierd formats

I disagree. The farther away the documentation is from the source code, the less likely it is to get written or updated. The best-maintained documentation is inline, like Javadocs, Python docstrings, pod, or doxygen comments. When you make a change to the source, the documentation you're invalidating is right there. It takes almost deliberate blindness to not keep it in sync.

Second best is a wiki. I

NaturalDoc

[SolitaryMan]

developers are far less likely to comment in wierd formats

Natural Docs [naturaldocs.org] can solve problem of weird formats. It is rather straitforward, looks nice in code and very easy to use. Besides, it allows you to write docs in separate files if developers really give up commenting in code. As for me, this is the best doc autogenerator I've ever seen.

Re:Don't auto generate

[rjshields]

Javadoc doesn't seem to suffer from the problems you mentioned. Most IDEs will insert and format Javadoc comments. When you have a One True Way of doing things, there's no problem sticking to it.

Ya!

[version5]

You're right. What sort of coder could possibly learn and understand complicated [www.foo.be], unforgiving [apache.org] syntax [ioccc.org]? The human mind was just not meant for such things!

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

Re:Do you really want to suceed at this?

[RingDev]

I don't know about that. Solid documentation can save maintenance time and reduce costs. It also makes bringing a new developer up to speed much easier. Wether you get canned, or a new employee is brought on, it's a good idea to have.

-Rick

Re:Do you really want to suceed at this?

[EraserMouseMan]

I totally agree with that. Documentation is good. It's just a running joke where I work that when the boss asks you to document your code he is considering replacing you. But the second half of my post indicated what you said about how it makes training easier. You've got to keep the docs updated though; and that seems like a full-time job sometimes.

My preferred methodology for documentation is to write very legible code using consistent naming conventions and coding patterns followed by a complete code

Re:Do you really want to suceed at this?

[anomalous cohort]

This is usually what a company asks an important developer to do before they let him/her go

You deserve a better company than that. If that is your company's style, then a move to another company is the best thing that could happen to you.

Commentator

[RAMMS+EIN]

Commentator [cenqua.com]. Because you _know_ the coders haven't properly commented their code.

Re:Commentator

[kwoff]

That's hilarious.

bitterness=9,profanity on

   int sum = 0;
   //don't even fucking *think* about asking
   for (int i= 0; i < a.length; i++) {
       sum += a[i];
   }

Generating API Documentation?

[weicco]

I figured out that you use Visual Studio .NET since you are programming VB.NET. If that's the case just enable "Generate XML Documentation File" from project properties and use code comments to generate documentation. I'm not sure how this is done in C/VB/VB.NET but in C# you use those /// comments. When you compile your project, Visual Studio generates XML file which has all the appropriate comments in it. After this you can use NDoc to generate real documentation in CHM, HTML2 or MSDN style formats.

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/ [compsoc.net]

Doxygen, gtk-doc, vbdox, ...

[Raphael]

Doxygen [stack.nl] 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 [doxys.dk]. It generates prettier output for C++ but may not support the other languages as well as Doxygen. Another tool inspired by Javadoc [sun.com] is PHPDoc [phpdoc.de] for PHP code. However, it does not seem to be actively developed anymore.

For plain C code, I prefer gtk-doc [gtk.org], 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 [gnome.org].

Since you also mention Visual Basic, you could have a look at VBDOX [sourceforge.net]. 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.

Robodoc

[pamar]

Robodoc is similar to Doxygen but is more liberal in the languages it can recognize/work with (i.e. it does not require a C-family syntax).

http://www.xs4all.nl/~rfsber/Robo/robodoc.html [xs4all.nl]

D OXYGEN

[ACORN_USER]

Agreed. I've used DOXYGEN, Javadoc and perldoc extensively for documentatoin. The beauty about the first two is that if your code makes sense and you haven't bothered to inline any documentation, you still end up with a 'GOOD' documentation detailing your code hierarchies, methods and accessors. That's the automagic you're after. Not sure if it'll support VB though.

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 [microsoft.com]. 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

Use Doxygen

[pixel_bc]

As other posters have mentioned - Doxygen rocks.

Re:Yes.

[Intron]

I was going to say that the correct tool is a Xerox copier. Take Appendix A of the software design document and copy it. If you don't have the API in your design document, then how do you know whether its right? If you didn't need a design document up front when the code was written, then why bother now? Just hand out the source and tell people the API is whatever is in there, cause you'll never figure it out now.

Doc-O-Matic

[eric2hill]

The professional version of Doc-O-Matic [doc-o-matic.com] supports .Net, Java, C++, Delphi, etc. It's a grand and does the same thing Doxygen does with a nice gui and super-easy customization.