Using JavaDoc or NDoc (XML) Commenting Formats

DocJet has interpreter modules for reading these commenting formats. In fact, DocJet can read any commenting scheme with the right plug-in. The JavaDoc and NDoc reading plug-ins are written using the API's published in the DocJet SDK.

There are some good reasons to think that the traditional form of commenting that DocJet uses is superior to writing comments with specialized markups. For example:

• Comments with markup in them are much harder to read. Remember that with or without a documentation tool, you still have to read the code -- just like you want your source code to be written in the most readable style possible, your comments should be readable as well.
• Comments with markup are harder to write. Afterall, the XML and JavaDoc formats were written to make life easier for the tool, not easier for you.
• Errors in markup are easy to make and difficult to detect.

For these reasons and others, we generally recommend that you only use the JavaDoc and XML translators as a transition. DocJet also comes with a tool that can read through your source files and convert comments written in those styles to the style best used by DocJet.