DocJet is a tool for generating documentation from comments in source code. The current version, 3.0, works with Java, Visual Basic, C, C++, and MS IDL.

How you add DocJet support to a project

The programs of DocJet aren't married into the workings of any development environment, but plug-ins have been written for Microsoft's Developer Studio and Visual Basic to make access to DocJet's features easier.

Microsoft Developer Studio

Visual Basic

In Visual Basic, DocJet is an "Add-In". You configure a VB project for DocJet by selecting "Add DocJet Support" from VB's "Add-Ins" menu, that takes you through DocJet's documentation wizard, where you specify what your documentation should look like and give other details of your project. When you have done that, you can choose "Generate Documentation" from the "Add-In" menu to build the documentation.

All Others

What happens when you generate documentation

Finding Comments

DocJet takes a different tack than most similar tools in this area. Most documentation tools insist that you put a magic sequence into your comments, or use a particular commenting convention, the tool then finds those comments and looks for the objects they document. The advantage to this approach is that the tool has an easy time of it. But there are a number of shortcomings to this approach, preeminent among them is the fact that you have to modify all your code in order to use the tool.

DocJet sees things from your perspective -- that is, it looks for objects in the code and then looks for a comment. The style of the comment is essentially irrelevant -- there are few commenting styles that DocJet cannot figure out. That means you don't have to modify your code to use DocJet.

And even if you have use a commenting style that DocJet can't grasp right off the bat, you can write a simple plug-in to explain it to DocJet. We'll talk more about that feature later. If you find yourself in this situation when you try DocJet, we suggest you modify a portion of your code to suit DocJet and test DocJet on that -- when you get more familiar with the tool, it'll be easier to write the plug-in.

Paragraph Formatting

Once DocJet has a comment, it doesn't just copy it verbatim into your output. In fact, it really goes to work on it, the first thing you will notice is that it breaks the comment down into paragraphs, and formats them so that they look nice in your output format. For instance, the documentation for the Connect class in the VB Add-In sample looks like this, with nicely formed paragraphs. The comment in the source code looks like your usual comment, with paragraphs separated by new lines.

DocJet can recognize a variety of paragraph styles, in addition to the fairly basic ones we talked about there. For instance, it can detect name/definition lists (See Connect.SetMenuState's source and documentation), it can see bullets, "Note" and "TODO" paragraphs.

Sections

DocJet also knows something about comment sections. If your comments aren't broken into sections like DocJet wants, fear not, DocJet will handle that too, but the output won't look quite as nice as it would if you had all the sections. If your section names are different, don't worry, it's easy to tell DocJet what maps to what.

Autolinking

When you mention an object in a comment, DocJet will replace that with a reference to the object's documentation. This requires no work on your part, it just happens.

The automatic linking mechanism is really more capable than just that, though. For instance, in most output formats, when you mention a parameter name, it gets italicized. In the Microsoft Word output formats, mentions of objects are left pretty much alone, except an index entry is entered, so your finished product will include a fully cross-referenced index.

Documentation for obvious things

DocJet knows what most objects it sees are, and it has default documentation for most of these. So, if your destructor does nothing fancy, don't document it, and DocJet will take care of stating the obvious for you.

That policy of filling in the obvious for you applies to inheritance in spades. DocJet will pull documentation for implementations from the documentation in the base class. Between these two features, you should never have to cut and paste documentation.

Enhancing your output

After you get your first DocJet output, you'll doubtless find some things that you want to improve. Usually there are two parts to an effort like this, one is simply to fill out your comments with all the sections, make sure all objects are commented, etc.

Until this point, all the information DocJet was using to build your documentation came from either your comments or from your source code. There are a number of ways for you to guide DocJet that go beyond source code and comments.

RTF and HTML documents

You can write a design document with Microsoft Word and add it to your DocJet project. To do this, save it in RTF format and add it to your project's source file list. (DevStudio users can simply add the RTF file to your project.) DocJet will translate the RTF into Microsoft Help or HTML, look for places where you mention the name of a documented object and replace them with hyperlinks to those objects.

If you are only building HTML output, you can write your design documents in HTML and DocJet will be just as happy. If you aren't as concerned about appearances, you can also just write ASCII (.TXT) files, and DocJet will handle those appropriately too.

DocJet has its own file format for glossary terms. The terms are introduced by lines starting with a >, and the following text is treated as a comment.