The Tools: Documentation generator

The tools I've discussed so far have obvious use for every developer. This one, however is something different. Most programmers do not use any source code documentation generators. Heck, I started using one only a few weeks ago! I like it so far.

So, what tools should you consider, when you're developing applications with C++? Well, the first one I thought of was doxygen. It is probably the most popular tool in the world. Most of the open source libraries use it. You want my own opinion? Well, it sure can parse C++ code, though it generates some stupid warnings occasionally. The actual documentation comments are ugly. I mean, really, writing commands like \ref or $ref is ugly. If you're reading The Code, and not The Documentation - the comments are very cryptic and hard to read. Another thing I should mention is that I really don't like that doxygen doesn't let you customize the look of generated documentation. I would really love if it would let me fully customize the generated output (by supplying my own templates for class, function, member, template class and so on).

Another tool I've found was Natural Docs. Now, the first thing I want to say is that the documentation comments are great! It doesn't have any commands or tags. When you look at the source code - it just look like normal comments. However, the tool isn't perfect either. Its' support for C++ language is far from perfect. On the web site, it says that the update in this area is planned, though. So, when they implement full support for C++ language - this tool will become the best tool. But right now it's barely usable. Also, just as doxygen, Natural Docs doesn't let you customize the generated output. Oh, and the supported output formats are fewer.

There were some other tools I've looked at. Some of them look nice, some of them are awful, but none of them deserve a separate paragraph in this blog-post. Anyway, here's is the list of tools worth mentioning:

There aren't that many tools that generate documentation from source code...

So, what is my final word? I choose Doxygen. I will be keeping an eye on Natural Docs, but for now, I choose Doxygen.

No comments: