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:

• Doxygen
• Natural Docs
  
• HeaderDoc
• ROBODoc

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.

The Tools: Text and Source Code Editor

Although IDE is the main tool to edit the source code, in some cases, you might need a good text editor too. Sometimes you just need to edit some text files (readme, license or something else), in some cases, you might even want to edit the source code without firing the IDE - a good text editor with syntax highlight is very handy in such situations.

Everyone could simply get away with Microsoft Notepad, although it's crappy if we talk about source code editing. The best free editor I've used so far is Notepad++. It isn't all that great all by itself, but it has some plug-ins that turn it into a very good source code editor. Namely, the Function List, TextFX and Light Explorer plug-ins are great!