XMLDoc in-source documentation style is becoming popular among Delphi open-source projects. There is also very good Delphi Documentation Guidelines document which describes what XML tags should be used for in-source XMLDoc-style documenting comments and how to use these tags. Unfortunately currently there are no documentation generators for Delphi in-source comments that fully support these guidelines.
So we must limit ourselves to the set of XML tags supported by the already available documentation generators. In fact I have found the only documentation generator that supports XMLDoc-style for Delphi in-source comments – that is Doc-O-Matic. There is also free (for non-commercial use) edition – Doc-O-Matic Express that can be downloaded from the official site. Using Doc-O-Matic Express one can generate documentation in several help formats; in this article we will see how to generate compiled html help (*.chm file).
For the demonstration purposes I downloaded Collections package by Alex Ciobanu; the project recently started to use XMLDoc-style in-source documenting comments.
Here is step-by-step instruction how to generate compiled html help using Doc-O-Matic Express 7.0:
Create the following directory structure:
Copy the “Collections” package files to the ‘Source’ subdirectory.
Run the Doc-O-Matic Express Configuration utility. Create a new Doc-O-Matic project and add all *.pas files from Source subdirectory to the project:
On the “General Options” panel set the project’s title (and other information if you like):
On the “Comment Finding” panel check “Use triple comments only” checkbox:
Now switch to HTML Help Tab; on the “HTML Help” panel set the name of *.chm file to be generated. The path to help compiler should already be set if help compiler is installed in your system; most probable it is installed already; if not download and install “HTML Help Workshop” from Microsoft – it is free:
We have created DoM project with necessary settings. Now we should use command-line documentation generator to create compiled HTML help file. To perform the compilation in a single click create a batch file collections.bat with a single text line like this:
“c:\Program Files\Doc-O-Matic 7 Express\domexpress.exe” -all c:\Work\Collections\DoM700\Collections.dox-express
The -all switch means to compile all configurations; we actually need only HTML Help configuration, but I have not found how to compile it alone, so I compile them all.