viksoe.dk

DocWizard

DocWizard


This article was submitted .


This MS Visual C++ 6.0 AppWizard adds automatic generated documentation in HTML Help to your ATL project.

The DevStudio AppWizard is aimed for ATL (and MFC) projects with an IDL file.
With just a few mouse-clicks you can automatically add documentation of your Object Model to your project.

The wizard will add a sub-project to your existing workspace.
When you compile this project, a custom build rule will automatically generate an HTML Help document describing the complete object hierarchy with object and method description from the IDL file (using the helpstring attribute) or directly from comments in the source code (using the JavaDoc commenting standard).

The build success depends on the HTML Help Workshop files, which must be installed and contain the HTML Help file compiler. You can freely download it from the Microsoft web site.

The documentation generator uses the IDL file's interface definitions to create a list of interfaces, structures and enumerations. It also looks for any helpstring attribute defined in the IDL file and attaches this to the initial (short) description of every interface.
To attach additional information to the documentation, the C++ source files are scanned (it looks for files with similar names as the interfaces) and adds any comments written with the JavaDoc commenting style.

The documentation layout is very similar to what you are used to see in the Microsoft MSDN library (as of June 2000). Formatting is controlled by style sheets (CSS files) and can also be partially configured using a configuration file to the IDL document parser.

IDL helpstring attribute

The helpstring attribute describes the IDL elements it is attached to. A simple text string is used. The use of special characters and even line feeds (new lines) are not encouraged. Use it to supply a single sentence describing the object.
[
  uuid(1e123456-1f3c-1069-996b-00dd010fe676), 
  helpstring("Line object attached to Shape"),
  oleautomation,
  dual
]
interface ILine : IDispatch                         
{
  ...
}

JavaDoc

The fathers of the Java language quickly did what C++ developers haven't yet been able to do: agreeing on a standard for source code comments.
JavaDoc is the preferred commenting technique for Java code. It's so simple and powerful that I tend to use it on my C++ projects as well.
The great intellisense support in Visual J++ for writing these comments brings tears to my eyes; too bad the C++ environment doesn't have it yet. JavaDoc is actually pretty simple. The text format used is HTML. You are even allowed to use HTML font formatting tags.
The output is controlled by a number of special tags starting with the at (@) sign. The tags are used to attach special comments for specific function arguments or to add additional information to the generated output (such as links to related objects).
/**
 * This first sentence is often used as a short description. The next
 * sentence and the remaining text explains the method in more details.
 *
 * @param argument1 This is a description of the first argument.
 * @param argument2 is also here. If the first letter is non-capital,
 *                  then the argument name is automatically pre-pended.
 *
 * @return An explanation of the return value.
 *
 * @see IAnotherInterface
 */
Several additional @ tags are used by DocWizard. Most of them adds special sections to the documentation.
@author The name of the author.
@remarks A special sections with remarks.

Notes

The source files include the source code for the IDLHELP utility, which is the one that scans the CPP and IDL files. The source code quality of this utility is appalling. I am sorry about that.

Source Code Dependencies

Microsoft Visual C++ 6.0
Microsoft MFC Library
Microsoft HTML Help Workshop

Installation Guide

  • Copy the .awx file to your Developer Studio Template folder.

See Also

EasyReg component for sample

Useful Links

JavaDoc standard

Download Files

DownloadBinary Files (51 Kb)
Source Code (41 Kb)

To the top