Setting up Visual C++ to use DOC++

DOC++ is a command line tool for generating documentation. It can be incorporated very easily into Microsoft's Visual C++ development environment for use with your projects. There are (at least) two ways to do this.

• As a "Custom Build" step in the build process
• As another Tool available from the Tools menu

The benefit with the first approach is that the documentation gets updated/regenerated every time you perform a build, so that it is always the most up-to-date. The drawback with this is that to regenerate the documentation, you have to build the project, and vice versa. This is why I prefer the second approach - described below.

By configuring DOC++ as just another Tool under the Tools menu, it is possible to generate the documentation for your project independently of the build. I tend to find that this saves time with development of code, and development pf the documentation.

General setup

While there are many ways of doing this, it is best to adopt a consistent approach across all projects. Here is the approach I have found to work best for me.

• In the project workspace directory (i.e. where the project, *.dsp, and workspace, *.dsw, files are stored), create a docs directory with two subdirectories. One named html, the other latex.

  Basically, the docs directory is used to store DOC++ "source" files. The html subdirectory is used to store the generated HTML documentation, and the latex subdirectory is used as a working directory for the LaTeX-related output.

• (Optional) In the docs directory, create (or copy from another project) a file banner.html. This file should contain HTML text (without the HTML, HEAD, BODY tags). It will be included at the bottom of every HTML page generated by DOC++. I like to include copyright information and similar in this footer, for example:

  <font size="-1">
  Copyright &copy; <a href="http://www.stevengould.org/">Steven Gould</a>, 2001-2002
  </font>

  The name of this file is entirely arbitrary. Later you will see where this name is passed to DOC++. If you use a different name, you'll need to modify the call to DOC++ later. Again, I would recommend being consistent across projects.

• (Optional) Copy docxx.sty from the DOC++ distribution. This is only used when generating LaTeX/PS output.
• Create your main DOC++ source file and call it WkspNameAPI.dxx. Refer to the DOC++ manual for details on the format of this file.

Setting up DOC++ under the Tools menu

Note that these notes refer to Visual C++ 6.0 (or Visual Studio 6.0). However, most of this should apply equally well to another other version. It's just that some of the menu and/or dialog names may be slightly different.

From the Tools menu, select Customize and select the Tools tab. This tab is used to customize the Visual C++ Tools menu. Make the changes described in the next two sections, then Close the Customize dialog. DOC++ should then be available for use from the Tools menu of Visual C++.

Creating a DOC++ (HTML Output) option

Under the Tools tab, scroll down to the bottom of the Menu contents list box and click on the line after the last entry. This will begin the definition of a custom tool. Now set up the following:

Creating a DOC++ (LaTeX Output) option

If you want to add another option to have DOC++ generate LaTeX output, then perform the following. Still in the Under the Tools tab on the Customize dialog, scroll down to the bottom of the Menu contents list box and click on the line after the last entry. This will begin the definition of a custom tool (just like we did in the previous step). Now set up the following:

Running DOC++ (from within Visual C++)

Once you have set up Visual C++ as described above, you should be able to run DOC++ from the Tools menu. The progress of the DOC++ command will be written to the Visual C++ Output window. The HTML documentation for your project will be created in the docs/html subdirectory of your project, and the LaTeX output (if generated) will be in the docs/latex subdirectory.