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

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.

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.

Re:doxygen, commentator

[Anonymous Coward]

The memory consumption can be "fixed" by linking it with a garbage collecting malloc library.

I don't know of a good one for Linux, but on Solaris I use libGCM and doxygen works great with large repositories, rarely using more than 2GB.

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

[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

[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. It's not right next to the code, but it's so easy to change. Also great if you have documentation that you share with other teams. (QA, other development groups, etc.) Wikis let them easily change things without digging through your source code.

(even when they do, its easy to typo and break the generator).

Then make the doc processing part of the normal build process. Especially if you're an automatic builder like Cruise Control. Just make that one of the steps. If it fails, Cruise Control sends out an email to everyone with the error message and the changes since the last successful build.

Secondly, for good documentation you need more than what an autogenerator can do anyway- good documentatition has examples, use cases, warnings and gotchas, etc.

There's no such thing as a documentation autogenerator. Just tools that reformat, add links and context, etc. You still have to write the words, and you still get to choose what they are. Having examples, use cases, warnings and gotchas is orthogonal to the software you use.

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

[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

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

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 different people on your team, you continually get reminded what works well and and what's not so great. You rely less on intelligent design, and more on evolution.

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 the algorithm and looking for bugs. Worse than useless all in all- it makes developers less effective.

And you missed my point- its not about developers not commenting, its about getting the syntax wrong and not getting it picked up, or not updating a comment. Some formats are worse than others with this. But if its too complex mistakes get made or people don't bother, thats human nature. Especially with deadlines (you did want us to get our work done on time, right?)

I'm all for code documentation. Auto-generation of it just doesn't work very well.

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 be doing from unit tests, you're in major problem already. Commenting and documentation exist outside of unit tests for a reason. They do things unit tests don't and can't do. Honestly I'd go without unit tests before I'd go without comments or docs from a code clarity standpoint.

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

[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 that they really need explaining, then they also probably need testing. I break those out into another object and test those separately.

For corner cases, if you're going to take the time to write them up in documentation, it seems much better to write them up in the unit tests. Documentation requires continuous manual verification to make sure it stays in sync. Unit tests can be automatically verified. The long-term carrying cost of a unit test is much lower.

And I'm not quite sure what you mean by side effects. Shouldn't the "unit" of the unit test stand alone?

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 explanation is doing half your job, if that.

You miss my point on corner cases entirely. Unit tests will never catch all corner cases, because humans are fallable. An abstract description can, or at the very least will leave exactly what is being done and what problems may exist far more clear.

You've never had code with side effects? Welcome to the real world. Code changes sometimes have unobvious effects when combined with other pieces of code. Alter a file, some memory, a global or class variable, and you'll frequently see odd results in other parts of the code. Unit tests can't predict this, and have no way of clearly warning you it can happen. Text can, and due to the greater descriptive power of English over C/C++/Java/other, they can illuminate possible problem areas, simply by listing everything global/class scope/outside the program they alter.

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

[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 for a couple of months and you may have a different opinion. Certainly I don't notice any of the problems you mention as being significant anymore.

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 talking about. Until then, I believe you're right to keep writing docs.

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 back on to tell us what we were actually supposed to be doing, otherwise we would have fixed the code to pass the test, and not worked in the real world.

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

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. The problems are orthogonal. Putting on layers of beauracratic bullshit like coding standards don't due anything but make a bad situation worse. Period.

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 within the context of any development project or orgainzation. Not having said methods in places increases the time it takes other developers to understand the code that's written and in some cases may lead to structral incompatibilities e.g. One developer prefers interfaces over inheritance.
It's also generally better to get agreement from the developers about how they want to work - it's not about shoving standards down everyone's throat. Standards are also great for new programmers that don't know any better. Setting them on a path that works for everyone is a Good Thing. As far as documentation goes - standard API documentation is important especially in larger teams. It's not a lot to ask to structure comments in an appropriate format. Most of the auto doc syntaxes are simple as well.
The problem with MS and what that article points to is that the messed up code base is a result of lack of control of developement - all the way around. Did you ever look at the code base for NT? It's a "mess". Nothing is done in consistant way - it's difficult to understand. This sort of code is a result of lack of technical leadership. Longhorn was scrapped not because brackets were in the wrong place but becuase of a lack of architectural leadership. It arguably more difficult to exercise this kind of control but it just goes along with my previous statements. Not only that but MS's plight highlights quite nicely why this sort of leadership should be instituted in a large development environment.

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:nDoc for all things .net

[Anonymous Coward]

And if your comments are in English that's as poor as your post, what good are they?

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 review/documentation after a main version is past the ever-changing design/prototyping/development stage.

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. 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];
   }

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.

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.

NaturalDoc

[SolitaryMan]

developers are far less likely to comment in wierd formats

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

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.

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

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. 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:Doxygen is not an answer yet

[Anonymous Coward]

I had similar complaints to yours. The tool I'm currently using to do my documentation is called NaturalDocs. It's not so much an autogeneration tool as a comment extractor and formatter; it doesn't do as much analysis as Doxygen, but being a control freak, I actually prefer it that way. Mainly, it's a way to keep my documentation with my code. And the output looks much better out of the box, IMNSHO.

Use Doxygen

[pixel_bc]

As other posters have mentioned - Doxygen rocks.

Yes.

[Anonymous Coward]

Documentation, API or otherwise is not "generated", it is "written" and "maintained". Anything less is pure lazyness and virtually useless. Just print out the damn header files! It's bad enough when a known system is used and proper pre-formatted commenting is done in code, "Generating" API docs for legacy systems that don't already contain copious amounts of in-line documentation, pre-formatted for a particular parser are is utterly futile.

"Software Engineering" suffers another great set-back from being a true discipline :(

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

Ya!

[version5]

You're right. What sort of coder could possibly learn and understand complicated, unforgiving syntax? The human mind was just not meant for such things!