Doc comments document the use and purpose of a program, and in that sense it actually belongs to the source code. In principle you are free to choose the way you want to document your code - if the documentation just stays in the source files. But if you work in a team that is probably not the way you want to read documentation. If you want it to be useful and accessible you want an up-to-date and easy-to-navigate API documentation.

Many languages have a means to generate API documentation. Javadoc was developed by Sun Microsystems as standard tool to generate documentation for Java code, and has been embraced by Flash programmers too, perhaps because of the similarities between Java and ActionScript 2.0.

Javadoc has a few rules that are easy to learn. So few in fact, that a lot of people have made up extra rules to be more flexible in writing documentation - the @example tag for example (now part of the Javadoc proposed tags). And like others, also I have added a few tags, you can find them below under Useful tags.

If you want to have the most portable doc comments, you should use Javadoc tags only. If you want to have more flexibility in generating your documentation, you can use the tags as described below under Commonly used tags and Useful tags.

The next sections lead you through the complete Javadoc/VisDoc syntax.