Generating Documentation

Imagix 4D's document generation facility enables you to automatically create detailed documentation from the information in the tool's database. By controlling the document's scope and format, you can generate documents for use in any of a wide number of scenarios. Common uses include:

Comprehensive Design Document. For your own code or code you've inherited, the best way to reference and study specific aspects of your software is normally to use Imagix 4D through its user interface. However, this may not be appropriate, due to budget limitations, technical constraints, or the need for a static design artifact. In such cases, a document covering the full project provides comprehensive design information with built-in navigation and some basic analysis.

Code Review Document. You can use Imagix 4D generated documents as a platform for structured code reviews. On a file, class or symbol level, you're able to automatically create a document with extensive details and analysis of the code unit being reviewed. Through the content and layout controls, you can ensure that the document fits easily with your standard review processes.

Change Impact or Problem Analysis Document. While using Imagix 4D to examine issues in the control flow or dependencies of your software, you may want to record your findings for communication or reference purposes. Again, you can do this inside the Imagix 4D user interface, using the bookmark function. However, if external documentation is wanted, a comprehensive record can be quickly and automatically generated through the document function.

Scope

Through the Document dialogs, you specify which portions of your software you want to cover and what types of information you'd like to include in your documentation. Imagix 4D will combine data in its database together with data that exists in your source files, and automatically generate the documentation.

The scope of the document is controlled in part by where you invoke the document function. The Document dialog can be opened from a number of places in the user interface. Depending on where it's called from, different scope choices will be available.

To document the entire project, open the Document dialog from the main menubar. To create a document about a specific file or class, for example for a code review document, right click on that file or class anywhere in the user interface; then, in the resulting context sensitive menu, choose the Document... action. If you're working in a Graph window and have created call graph of function dependencies that you want to document, invoke the dialog through that Graph window's local menubar.

Formats

The Document function produces output in three formats - ASCII, RTF and HTML - to support different uses. While any document can actually be produced in any of the three formats, each of the formats has certain advantages. Typically, there is one obvious choice for a given document use.

ASCII format results in simple, readable files. Generating and post-processing ASCII documents is one quick way to export information from Imagix 4D. If you have more advanced data export or custom report needs, please contact Imagix or your local distributor, as the tool has an extensive database with powerful analysis and export capabilities.

With RTF (rich text format), you can produce hardcopy documentation. The Imagix 4D creates a (series of) files, that you can import into your word processor. For large documents, you can then use your word processing tools to control type styles and page layout; to generate a table of contents with your word processor, use `Section' and `Subsection' as the styles to include in the table. However, RTF is normally the format choice for smaller code review or problem analysis type documents. For these, a table of contents is often unnecessary. You can quickly add whatever annotations you want using your word processor, and then generate a paper or electronic document that can be shared for the task at hand.

The HTML format enables you to create on-line documentation with extensive indices. All symbol references are linked, including symbols appearing in graphs. Metrics tables and class hierarchies are included. For comprehensive design documents, this is usually the format of choice.

Contents and Layout

Within the scope of the project, you have wide control over the contents of the documentation output. You're able to specify which symbol types are included and what information is generated about each included symbol. As you're getting started with Imagix 4D, the easiest way to control this is through the Document Settings dialog. There, a tabbed series of checkboxes enable you to specify such things as which metrics to include and what comment style to look for.

The definition of what information is available for a given symbol type, and the order that that information appears, is controlled through the ../imagix/user/user_doc.txt template. Advanced users might want to review and modify this file to optimize the output for their use. Instructions for doing this are contained in the file itself. Before making any changes, be sure to make a copy of the original file.

DocGen sheets offer an alternative to the Document Settings dialog and the user_doc.txt template. Through the DocGen sheets, you're able to specify the same things you did through the dialog and template, and then store those settings between sessions. Furthermore, the DocGen sheets enable you to control many more aspects about the document and its build process. These range from appearance factors as page width and graph size to such build issues as distributed document generation.

Any .dgn file located in the ../imagix/user/doc_gen directory can be applied through the Document dialog. There is a sample DocGen sheet (../imagix/user/doc_gen/sample.dg_) which contains information on all the settings that can be made in the sheets.

By building up a series of DocGen sheets, you can create a collection of easily applied document style definitions, each optimized for generating a specific document type.