the toe of webdev

If you write programs or “code applications,” then you should seriously check into the standard commenting and API documentation syntax available to that language.

This has 2 primary benefits, possible others:

1. You learn to properly comment your code.
2. Your code explains itself to other programmers.

And anything that increases your efficiency and aptitude in something you enjoy either as a hobbyist or as a professional can only result in positive learning — the best kind.

Wikipedia’s comparison of documentation generators can be found here. This lists the majority of those I could possibly think to show you, so make sure to research the language you code with.

These tools generate API documentation based on your properly formatted comments.

The ones I keep in mind are:

• JSDoc for JavaScript
• Apydia for Python
• GTK-Doc for C
• phpDocumentor for PHP
• See “best for last” at the bottom of the page for PHP, C#, and Python.

Otherwise, I have not used any others, but I have heard that:

• Doc-O-Matic
• ROBODoc
• TwinText
• Universal Report

Are the most robust.  And the article I provided earlier illustrates that same assumption.

I believe I saved the best for last, and that is Doxygen.  As far as I know, Doxygen can automatically generate well-formatted API documentation for several languages and is by far the most robust*.  If it currently had deep support for JavaScript and/or ASM (assembler or assembly) I would tentatively call it the ultimate and only tool necessary.

* Please let me know if there is a more robust or preferred tool — either by industry or by popularity.

Trackback URI | Comments RSS