Document Generation

Create Document Projects for C++ in Developer's Studio

Your first step toward generating documentation is to open the Developers Studio and open the project workspace for which you want to generate documentation. From here, create a documentation project within your workspace. This project will behave like any other project in your workspace. It will contain files, and it can be "built", the difference is that its product is documentation, not an executable.
 
Choose New from the File menu and select the Projects tab.
  1. Fill in the project-name field (probably with "Documentation").
  2. Select the radio button that says "add to current workspace".
  3. Place the documentation project in the topmost directory, by overriding the default behavior of the dialog. The default behavior of the dialog will cause the documentation project (and all the files DocJet will create in it), to be placed in a subdirectory. DocJet needs to store paths to your projects and their source files and wants to use relative paths to do that, which will be the case when the default behavior is overridden. You can move your project, if DocJet uses relative paths.
  4. Press OK
  5. You will be entering the DocJet AppWizard, which is a series of dialogs designed to help you inform DocJet of what your project will look like. These dialogs are largely self-explanatory. You can find details in the DocJet Help file.
  6. In step 5 of the Wizard screens, you select which output formats you want to generate documentation for. Select AdvantHTML when you want to use this format, and remove the check boxes from the default HTML and MS Help.
  7. Figure 3-1. DocJet Wizard

     

  8. DocJet will create a file main.cpp, which you can see if you open the "Source Files" for the documentation project in the files view. Remove it, otherwise you need to check it in into the version control system. When you generate your documentation ("build it"), you will get a warning, but it can be ignored.
  9. Generate the documentation by compiling the created documentation project. The output of the DocJet generator will come out on the Output view of the Developer Studio. Read and correct the error and warning messages from the document generation in the same way you do messages from the C++ compiler.
  10. View your documentation by using the Explorer. Move to the directory where your files were generated and open the documents.
  11. To change the settings of DocJet from those set up by the AppWizard, open the Documentation project from your project's FileView, find <project name>.djt and double-click it. This will bring up the DocJet Configuration Editor, where you can change the project's documentation configuration. To change for all projects you need to change the default configuration.

Files to Include

Include only those files (header and implementation files) that are interesting to generate documentation from. If you take all files in the project, there may, for example, be a lot of documentation generated for constants which are of no interests for others. You will get a lot of warnings when generating the documentation, because you have not commented these constants.
When dealing with a project that contains IDL files, you need to specifically direct DocJet not to look at the .c and .h files generated by the IDL compiler. Do this through the Sources page of the Configuration Editor.

COM Interfaces

When generating documentation for COM interfaces, where you want to use the comments from the C/C++ implementation file, you need to have a keyword in the IDL file (see Chapter See COM Interfaces and IDL ) and use a special rewriter DLL, the IDL Comment Map Hook. You must tell your project to use the hook by following these steps:
 
  1. Start the DocJet Configuration Editor on your project's .djt file, by double-clicking the .djt file under your documentation project.
  2. Turn to the General page. Check the box beside IDL Comment Map Hook. See See General page of a DocJet
  3. Figure 3-2. General Page of a DocJet Configuration
     

  4. Press OK.
 

Manage Document Projects for Visual Basic 5.0

Create a document project:
  1. Choose the Add DocJet Support from the Add-Ins menu.
  2. When you do that, you will enter into the DocJet AppWizard dialogs. It creates a DocJet Configuration file that has the same name as your Visual Basic project with a .djt extension. This file is created in the same directory as your Visual Basic project (vbp) file.
Generate documentation:
  1. Choose Generate Documentation from the Add-Ins menu.
  2. It will execute the generator and send its results to a dialog box. There is a checkbox on this dialog that controls whether the documentation that is generated will be immediately displayed when documentation generation is complete.

Change your configuration:
  1. Choose DocJet Configuration from the Add-Ins menu to open the DocJet Configuration Editor.
  2. Do the changes you want in your document project configuration.

Files to Include

Include those Visual Basic files (forms, classes, modules) that you want to have documentation generated for. Normally, this is all files found in the Visual Basic project.

Generated Documentation

The default location for the generated documentation is in a subdirectory of a directory called Documentation, which DocJet creates in your project's root directory (the same directory where your .djt file is). The subdirectory of Documentation has the same name as the output format(s) you generated, so, for example, if you generated "AdvantHTML", the directory is called Documentation\AdvantHTML. The exact file that you want to start with depends on the type of output you generated.
If you have created two document projects in the same directory, for example to generate documentation both for external interfaces and for a design specification, you must change one of your documentation projects to put the generated output in something else than the default Documentation. You can change this by the DocJet Configuration Editor:
  1. Start the DocJet Configuration Editor for your project's .djt file.
  2. Select the Variables page.
  3. Choose the OutputDir variable.
  4. Select the Output Formats you want to generate documentation for and change the directory name to something else than Documentation.
Some of the generated documentation is described below, but you can find other output formats.

HTML and AdvantHTML Documentation

HTML and AdvantHTML documentation creates a file for each method, variable, etc. but also generates a table of contents file (contents.html) and an index file (index.html). There are framed variants of both of these called contentsf.html and indexf.html.

HTML Help Documentation

HTMLHelp documentation is generated to a file called help.chm. In this output format and the MSHelp output format, DocJet does not actually produce the final output itself. Instead, it produces input to the HTMLHelp Compiler. This input (lots and lots of HTML files) is left in the directory.

MSWord Documentation

Microsoft Word documentation produces a file called reference.rtf which contains most of your documentation. This file should be used indirectly, though. The file, manual.doc includes reference.rtf. This allows you to create your own title page, pagination schemes, and stylesheets without having to contend with the Output Format Editor. We recommend you take a look at the tutorial, "How Can I Integrate DocJet's Printable output into Production Documentation". In addition to talking about how to do sophisticated things like attaching stylesheets, integrating other documents into the output, it also gives you a basic grounding on some things you may not be familiar with, such as Microsofts Word's indexing mechanisms and field codes.
For the moment ABB does not have any special template for this generation, it may be added later.

MSHelp Documentation

MSHelp documentation is in mhelp.hlp and mhelp.cnt. As with HTMLHelp, this is a compiled format; the intermediate files, mhelp.rtf, mhelp.hpj, and others are left in the directory.
MSWord will be unable to read mhelp.rtf. Another foible of MSHelp output is that you cannot just rename mhelp.hlp and mhelp.cnt, since mhelp.cnt is compiled into mhelp.hlp. If you want to change the name, do so through the Output File Name global variable.

You can direct DocJet to place its output somewhere else with the OutputDir variable. Usually, though, the only reason why you might want to do this is to move the output to its production location, and in most cases, it is better to copy the files manually, or with a shell script tied to your makefile.

Additional DLLs

DocJet has additional DLLs and other extras on its support page (www.talltree.com/docjet/support). Look at this page if you need anything special. Download the things you need and follow the instructions for each installation.
The WinSDE installation adds three of these DLLs automatically, the GetEnv DLL (see See Get Environment Variables ) the IDL Comment Map Hook (see See COM Interfaces ), and the Afx Hook (see See Afx Hook ).

WinSDE also adds an own extension DLL, SdeDate (see See SdeDate DLL ).

Get Environment Variables

The extension DLL GetEnv fetches environment variables from the environment, with getenv.
The DLL is used to put some information from the build environment into the documentation - such as the version number.

You may have a particular spot you want to use GetEnv. A common spot to put stuff like this is in the Terms global variable. The contents of this variable is shown in the upper right corner of each page. Usually, this is for copyright and disclosure warnings, but it makes a fine spot for a version number too. If you want to go this route and just want to GetEnv to a specific project, follow the steps below:

  1. Start the configuration editor on your project.
  2. Go to the Variables page.
  3. Select Terms from the list of variables.
  4. Select the output format you are generating.
  5. In the value field, type in the text you want to use. Where you want to put the environment variable, pull down the menu by right-clicking. Select GetEnv off of the Miscellaneous sub-menu. Between the ":" and the "<<" type in the name of the environment variable.
        Your screen should look like:
 
  1. If you are generating several output formats, repeat the last two steps for each output format.
  2. Press OK.

Afx Hook

The rewriter's DLL "Afx Hook" can be used when the "Afx" keyword is found in comments. It will not generate documentation for comments including the "Afx" word. Normally, these comments are generated by wizards, and if these comments are included in the documentation, it may not be the correct comments.
Do the following when you want to use the dll:
  1. Start the DocJet Configuration Editor for your project.
  2. Select the General page (see See General page of a DocJet Configuration ).
  3. Put a check mark near the Afx Hook, in the list of rewriter's dlls.
  4. Press OK.

SdeDate DLL

The SdeDate DLL can be used to get the date when the document is being generated, and put it in the generated documentation.

One example of how to use it is in the page trailer for the Output Format. You add it by the Output Formats Editor. Open the output format you want to change, go to the Procedures part and open "Page Elements.Trailer". An example of a page trailer is found in See Page Elements.Trailer in Procedures .

Output Formats

In your project's .djt file you select the output formats you want to use. We have added a template for HTML, it is called AdvantHTML.

If you want to do some more changes you can do it for each project, in the Output Formats. See the DocJet Help.

You can also do other changes, and create your own output formats, with the Output Formats Editor, see the DocJet Help.

AdvantHTML

The following changes are done in the AdvantHTML template compared to the original HTML template:.
 
Changes in AdvantHTML
Section
Name
Change Description
Output Files/Contents
Preliminaries
Title added, font size changed.
Output Files/Contents
Index Entry
Index Entry added in Contents part to have a link to the Index in the Contents part.
Output Files/Contents - Frames
Preliminaries
Title added, font size changed.
Output Files/Contents - Frames
Index Entry
Index Entry added in Contents part to have a link to the Index in the Contents part.
Output Files/Index - Frames
Title
Font size changed, horizontal line added.
Paragraph Styles
Glossary Word
Font Size changed.
Paragraph Styles
Index Head 1
Font Size changed.
Paragraph Styles
Subheading
Font Size changed, bullet removed.
Paragraph Styles
Title
Font Size changed.
Procedures
Links.Index
Links.Index added, include the code executed when creating a link to the Index file. 
Procedures
Page Elements.Trailer
Modified to include the document generation date, product name, product version and copyright text. Starts with a horizontal line. 
Topics
Member Variable
A Description part is added, bullets are removed.
Topics
Class Overview
A Description part is added, which will be shown with the keyword description if it exists, otherwise it will just be shown as text, as in the original file.
Topics
Methods
A Description part is added, starting with the word description, bullets are removed.
Topics
COM Classes
A Description part is added, bullets are removed.
Topics
Type Libraries
A Description part is added, bullets are removed.
Variables
Company Name
Variable added to set up the current company name, default is ABB Industrial Products. The variable is used in variable copyright.
Variables
Copyright
Variable added to set up a copyright text, including Company Name. The variable is used in Page Elements.Trailer.
Variables
Output Dir
Variable changed to put the output in AdvantHTML.
Variables
Product Name
Variable added to set up a product name. The variable is used in Page elements.Trailer.
Variables
Product Version
Variable added to set up a product version. The variable is used in Page Elements.Trailer.
Variables
Title
Modified to "Development Project".
 
The AdvantHTML template defines/modifies some variables, which are used in different part of the output format. The value of these variables should be changed for each project, in the Output Formats. The following variables are created/modified:
 
Company Name
The Company Name is used when setting up the copyright text. The default ABB Industrial Products should be changed to your company name.
Copyright
Copyright is used when in the trailer of each generated page. Change it if you want another text.
Output Dir
The directory where DocJet places the generated document. Set to Documentation/AdvantHtml, it can be necessary to change it to another directory. 
For example <DocJet project name>/AdvantHTML.
Product Name
Product Name is used in the trailer of each generated page. The default value is empty, you can change it to the product name you generate documentation for.
Product Version
Product Version is used in the trailer of each generated page. The default value is empty, you can change it to the product version you generate documentation for.
Title
Title is used as a header in the contents part. Change the default value to something, for example project name, that you want to have as title.
 
An example of documentation generated with this template is found in See Example of generated HTML documentation in See COM Interfaces and IDL .

Start Page for HTML documentation

When you start a web browser on the framed contents, or framed index, you see a blank page on the right side. If you want to include something in this blank page, you can edit the output format:
  1. Start the Output Formats Editor and select the output format you want to change.
  2. Select the section Output Files/Blank File.
  3. Change the text part. You can include the text you want to have in the file blank.html.

Use the variable Home

You can define the variable Home for each DocJet project. When you have defined it, it will be used as the home page for the project. The contents part will include a link to this page.

Do the following to use the variable Home:

  1. You must include the html file that you want to use as home page in your documentation project. Do it when you create the project, or later from the DocJet Configuration Editor opened on the project. Select the Sources page, and add the file. Example:


  2. Go to the Variables page in the DocJet Configuration editor.
  3. Select the Home variable, and the output format that you want to change.
  4. Fill in the title (specified with the HTML keyword title) of the home page you want to use. Note, that it should not be a file name, or a web address, but the title.

Default Configuration

The default configuration is used for all project's created from it. It can be changed by DocJet's Configuration Editor, see the DocJet Help.

Using DocJet from the Command Line

This is an important section to read even if you stick to using DocJet through Visual Basic or the Developer Studio exclusively. Reading this will show you how DocJet is tied in with your particular development environment and thus show you how you can further enhance the tie-in. If you use a development environment other than MS Developer's Studio or Visual Basic 5.0, this can give you hints on how to manually install DocJet into the environment you use.

There are two DocJet executables that you need to know about, and their command-line argument structures are simple. Some of them are shown below, see the DocJet Help for a more thorough help.

Editor and AppWizard

Editor.exe is responsible for the Configuration Editor and the DocJet AppWizard dialogs. Usually, it is invoked with just:
 
.../Editor "my project.djt"

If my project.djt exists, the Editor will pop up the configuration editor on this project. If not, it will pop up the AppWizard dialogs and create it. If you are invoking the editor for this purpose, you can append /p and then the paths of all the source projects to include in the project. By "source projects" we mean Visual Basic project files (.vbp files), Developer's Studio project files (.dsp), or Makefiles (Makefile's or .mak files). You might come up with a command line like:

.../Editor.exe "my project.djt" /p "my project.vbp" "my dll.dsp"

The Generator

The argument list of the generator is even simpler. It takes the name of the configuration file (the .djt file) and these optional arguments:
 
-b
Suppress the copyright banner.
-v
Print verbose messages as it goes.
-t
Launch a viewer on the documentation when generation is complete.
-f <dof-file>
Override the output format selection in the configuration file and generate the output format defined by dof-file.
-h <hook>
Override the Rewriter Hooks section of the configuration file, use the rewriter hook DLL specified in hook. You can have several entries like this on a command line, specifying a series of rewriters to apply. The order they appear in the command line is the order they will be applied in.
-h -
Override the Rewriter Hooks section of the configuration file, use no rewriter hook DLL's at all.
 
 
This is a common command line:

.../Generator.exe -v -b -t "my project.djt"

Example of make rule

If you want to create a make rule for DocJet, you will want to put something like this in your makefile, e.g. NMAKE or Gnu Make:
 
documentation: FORCE
    @echo Generating Documentation...
    @cd ..
    @C:\DocJet\Program\generator.exe -v demo.djt