Can I integrate design documents, etc. into the output?

Comments on objects make up the great bulk of an API document, but if that's all that your document is made out of, it will be difficult to read. What's needed to complete the picture are overview documents designed to help the reader see the relationships between objects.

To understand why this is so, and why it's important to use a documentation tool that takes this requirement seriously, one has but to look at the consequences of failing to do this. Consider this page from the .Net Framework SDK:

There's almost nothing on this page that you couldn't have gleaned from the declaration. When do changes to this property actually display on the screen? Do you need to redraw? What do they mean by "ambient"? What exactly constitutes the "background"? One would hope that the root class, AmbientProperties, would tell us what ambient properties are, but no, it really doesn't. We might hope that the link to BackColor will yield answers to the issue of what constitutes "background", but that turns out not to be the case either. The reality is that we have an object with a page full of "documentation" that says absolutely nothing.

It's easy to blame the writer of this comment for its shortcomings, but put yourself in their shoes. What would you write? It wouldn't be appropriate to discuss background colors here, would it? Not in the code, no; the notion of "background" is wider than one or two properties. Similarly for ambient properties - you couldn't properly discuss ambient properties without contrasting them with primary properties.

People don't set out to write comments like poor BackColor here, they just end up doing it when the documentation tool they are using doesn't offer them an alternative. The real shortcomings here are those of the tool, not the author. Neither NDoc nor JavaDoc provide any meaningful way to integrate externally-written documents into the documentation-set. Further, they have only the most limited of means of controlling what the table of contents looks like - they just dump the objects out by a combination of code-structure and alphabetical order.

How would using DocJet help?

DocJet's approach to this problem is reflects the varied ways in which conceptual topics like this can be discussed. But at the heart of the solution is DocJet's table of contents editing tool, a screenshot of which is shown below.

Within the table of contents, there are two ways that you can add overview data. First, you can edit the text within the tool. You enter the text as you would a comment, using ASCII formatting. Although these ASCII formatting rules are powerful, if you have a lot to say on the subject, you might consider creating a separate document and inserting a pointer to it in the table of contents.

Creating a separate document is straightforward, the only requirement is that you save it as HTML. So, for example, you could create a document in Microsoft Word, save it as HTML, and then place it in the table of contents by dragging it from the Windows Explorer. When you generate documentation, DocJet scans the HTML file, makes sure any images, scripts, or other sundry files get copied into the output, and also uses its automatic hyperlinking.

The automatic hyperlinking makes it so that, when you are creating your document, all you have to do to generate a hyperlink is mention the name of an object in the code - DocJet will take care of turning it into a hyperlink. You can easily create links from the code to your documents as well. You just mention the title of the document in the comment and DocJet will turn it into a hyperlink to the document.

Glossary Terms

In addition to the various kinds of supporting documents you need to make a good document, you might also want to define some terms that mean something special in the context of your code. You can do that with this tool as well. After you create a glossary term, any time you mention it in a comment, it gets replaced with a hover-over link - that is, when a reader puts the cursor over the term, a small window pops up with your comment in it.

Images in Comments

Sometimes the best way to explain something is with an image. Obviously, there's no way to express something like this with ASCII markup, so there is some special syntax that you have to use:

// The following call diagram shows the
// allowable transition states for this class:
//
//   {image:CFoo_transition_states}

"CFoo_transition_states" needs to be the root file name of a JPG, GIF, TIF or PNG that you declare in the images section of the table of contents editing tool. There are a number of advantages to not requiring the extension in the comment. First, it's shorter. Second, you might change your mind on the image's file format. Third, suppose you are creating both on-line and printed versions of your document. For the printed version, you will need a very high-resolution of the image, but for the on-line, this extra resolution would be useless and would make the final documentation set unbearably large. Thus DocJet lets you define two versions of each image, one for printed, one for on-line.

Furthermore, if you declare an image to DocJet and use it within an externally-prepared document, DocJet will make sure that the appropriate image file is used in the output.

Organizing Objects in the Table of Contents

You can assign objects to their place within the table of contents either within the editor or by magic keywords in the code. Assigning objects to their place in the table of contents is a good choice if you are producing a reasonably small project and you are primarily worried about one delivery of the document.

This approach is obviously less maintainable than putting keywords in the code. If you add a new object, you will probably comment the object, but you probably would not fire up this tool and assign it to its spot in the table of contents right away. So, if you are interested in maintaining a document that is consistent with the build, putting keywords in the code is the way to go.

However, if you are producing maintenance documentation, oftentimes the best plan is to organize your documentation's table of contents based on the directory and file structure that you use to organize your code. If this is your case, DocJet can do that too. Typically, in this case, you can leave the table of contents editor alone. DocJet has the ability to automatically construct a table of contents for you, based on file/directory layout. It can also pick up overview information from text files in the directory and/or leading comments in your source files.

Again, the thing to understand is that DocJet is built on a philosophy of working with whatever you are doing, not enforcing our way of doing things.