Logo Homepage:

JADD - Just Another DelphiDoc

Table of Contents


This is a very short description what to do to generate some documentation. Please use the F1 key to access the corresponding help.

When the program starts the welcome register is shown, with the tree view on left another one of more then two dozen registers can be shown. As can be seen from the layout of the tree view the program consists roughly of two parts. With the first part under the main entry "Acquire Parsed Data" some source code files can be parsed, on which in the second part below "Generate Documentation" exactly this can be done.

To parse new source files the register "Select Files" should be shown and the source files be added to its list. This is simplest done by dragging the project file, the .dpr-file, from the explorer in the form and checking the new entry. After that is done on the register "Parse" the button with the same caption can be used to parse the source code. If conditional compiling is used within the project the version of Delphi to emulate while parsing the source code can be selected in the register "Compiler Options" before the code is parsed.

Now the format of the documentation to be generated can be selected on the register "Select Generator". The generators and all other objects that are used to create the documentation have several (lots of) options to tweak the gathering of information and the result. The button "By Category" will show a dialog to edit the options of the generator.
Then the register "Generate" should be selected. Here the directory to generate the documentation to can be entered, it should be empty because all files in it will be overwritten when they are part of the new documentation and already exist. The directory will be created if it does not exist. All options of all objects used to generate the documentation can be edited again with the button "Edit all Options by Category". And finally the generation of the documentation can be started by pressing the button "Generate Documentation".

Generating Documentation as a help on a Graphical User Interface (GUI)

To generate documentation as a help on a GUI there are three steps to do: Generating a log file, writing the documentation and generating the final documentation in the target format.

In order to generate the log file the unit UFormHelp in the directory GUI in the source tree has to be included in the application. The unit will automatically show a window to generate a log file of all visible components on a form of the application and save a screen shot of it. The currently active window should automatically be selected, if there is a page control on the page a prefix of the currently active page should also automatically be set. To use the window with modal dialogs there is also a button to re-show the window after a few seconds after the modal window has been shown, so it can still be accessed.
When the generation of the log file is started it is generated in the specified directory. The name of the file is assembled from the name of the form, the prefix and the extension .log. The screen shot is saved in a file with the same name but with the extension .bmp.

The documentation of the GUI is written in simple text files, just like additional user documentation. It has to be in a file with the same name as the log file but with the extension .txt. The documentation itself is in ~GUI sections similar to the additional user documentation's ~Page sections.
Other files may be included in ~GUIInclude sections, similar to the ~[userDoc ] inline command. Aliases to let several components use the same documentation can be defined in ~GUIAlias sections, additional regions in the screen shot may be defined as links manually in ~GUIManual sections. Links to the documentation topics can be generated within this documentation or the additonal user documentation with the ~[linkGUI ] inline command similar to the ~[linkPage ] command of the user documentation.
Please see the documentation on these sections and the inline command. Also notice the three special topics for the ~GUI sections.

In order to generate the documentation in the final format with DelphiDoc the appropriate generator has to be chosen and the log files of the GUIs to generate the documentation about be added in the register "GUI Help Log Files". Then the button "Generate Help on GUI" on the next register can be used.

As always you change some options of the generator before generating the documentation, localize some used texts or define some files with additional user documentation to include. There are four options specific to this kind of documentation, first two for all generators (in TJaddCommentData or TFormatCommentDoc), the option UseAutoAliases to specify whether the automatically generated aliases (from labels to the control they describe (linked via their FocusControl property)) should be used and the other GUIHelpUseTopicAsLinkText to specify the alternative texts for the links inside the screen shot for the HTML formats, if it is enabled the title of its comment will be used instead of the name of the component.
The two other options are specific to the PDF generator, more precisely to the screen shot in this format: InterpolateGUIHelpImages and MaxGUIHelpImageScale. Take a look at the descriptions of all options.

The Windows Help file and the HTML Help file also use the HelpContext property of the components and links the help topics to them, so you can use the generated help file directly for your application simply by specifying it in the project options. Of course it would also be good to rename it to a fitting name for your application (i.e. the same name as the executable with the extension .hlp or .chm). The number of the help context can also be defined manually in the comments with the inline command ~[HelpContext <number>].

The Graphical User Interface (GUI)

There is also a generated documentation for the GUI available. Choose the window you want to read the help about and click on the image at the top on the component you want. On the main window you may, as in the original window, also click on in the tree at the left to change the current page.

This documentation is now also included as a Windows HTML Help file directly with the executable file, so you may simple press F1 in the program as well.

Command Line Parameters

Both, the GUI and the command line version support parameters specified when starting the program. For the command line version these are mandatory. Some of these options only work or only make sense for one of the versions, in that case they'll be ignored by the other version.

The command line parameters have been completely revised in version In most cases old parameters can still be used without much change needed. The main difference in the concept is that now each parameter is parsed one after another, each one is treated as a command that will be executed directly, so parsing of the parameters works much like a batch file. Previously first a set of parameters where parsed, and only when the set was completely specified the whole set was executed. The most obvious change in that regard will probably be in the GUI version when the -p switch is used to load a project file. While in the old version the source files were only parsed when the set was finished (either by loading another file or with the -a switch), now the files will be parsed directly. This has also an effect on the order the parameters should be specified, while in the old version a new set was started with the -p switch and the options for the set had to be specified after it, now all options pertaining the parsing have to be specified before the project file is loaded.

The command line is also now parsed according to the rules used by Microsoft, avoiding the buggy ParamStr and ParamCount functions. Additionally the parameters are now specified similar to GNU's implementation of the getopt function defined in POSIX. This means that there is a long option for each short option, and even some options for which only a long version exists. Generally, the new long-options are recommend. The short options are also now all case-sensitive, but they can be merged into a single parameter like for example:
-pdgFro dd.ddp .\_doc TICWinHelpDoc AutoLaunchDocumentation=true
Long options can be abbreviated as long as their meaning is not ambiguous, for instance "--so=FILE" can also be used instead of "--sourceproject=FILE".

The list of parameters follows. On Windows "/" can also be used instead of "-" for short options. When loading project files the name "-" can also be specified in the command line version to load the file from stdin/Input. "[-]" on a line on its own (i.e. an initialization section with the name "-") is treated as the end of the file, in case several files should be read from the standard input stream of the program.

Additionally to the parameters listed here, the command line version checks whether the first parameter is "-auto". If this is not the case it will wait for the user to press the enter key when it has finished parsing all parameters.

-h, -?, --help
Shows a help text about the command line switches of the program and aborts any further parsing of the command line. But beware that any parameters before it will be executed.
-p FILE, --sourceproject=FILE
Loads a project file defining lists of sources files to be parsed and with which options they should be parsed. After loading these information the current generator objects try to read their options from the file and localized versions of the texts are also loaded if available. Due to this, the generator objects should be selected before loading the project file. After that the source files are automatically parsed.
-e FILE, --executable=FILE
Tries to select source files to be parsed by the executable file specified after the option. If a project file exists with the same name (but different extension) it is loaded like with the -p option. If not either the .dpr file with the same name is added to the list of files to be parsed or, if it does not exist, the directory containing the executable file. Then the selected files are parsed.
By adding DelphiDoc to the Tools-menue of Delphi and entering the parameters "$SAVEALL $SAVE -e $EXENAME" (and others) it's relatively easy to generate documentation for the current project.
-P FILE, --loadparseddata=FILE
Loads previously parsed data from a file.
The -k switch is no longer supported. It is not necessary anymore as options no longer have to be in sets.
-g NAME, --generator=NAME
Selects a generator object to be used to generate documentation. Either the idenfication or the name of the class can be used to specify a generator, the idenfication is recommended.
-d PATH, --docpath=PATH
Specifies the directory to generate the documentation to. It will be created if it does not exist. If it exists it should be noted that all files in it will be overwritten if they share the same name as a file of the documentation.
Specifies the name of the file the documentation should be generated to. This option is ignored if the generator has no option "FileName" and is in the other case equivalent to --genoption=FileName=FILE.
-o NAME=VALUE, --genoption=NAME=VALUE
Sets the value of an option of one of the generator objects. The option to be set is specified by its name, after a separating equals sign "=" follows the string representation of its new value. Remember to quote the value if it contains any whitespaces.
-l NAME=VALUE, --localize=NAME=VALUE
Sets a localized version of a text to be used in the documentation to be generated. The text is specified by its name, after a separating equals sign "=" follows the its new value. Remember to quote the text if it contains any spaces.
-L FILE, --loadlocalization=FILE
Loads localized versions of the texts to be used in the documentation to be generated from a file. The texts have to be defined in an initialization section of the name "TEditDocumentationTexts". The names are the names of the texts to be localized and their values the corresponding localized versions. The texts should probably be quoted to ensure leading and trailing spaces are not lost.
If the file does not exists and the short option -L is used it will instead be interpreted as the option --uselanguage.
Uses the localized texts of a predefined language when generating the documentation. Currently only "English" and "German"/"Deutsch" are predefined, unknown values will be ignored.
-u FILE, --userdoc=FILE
Adds a file with additional user documentation to the list of files. Generally only one or a few files should be added, other files should be included with them with the inline command ~[userdoc ].
-U, --clearuserdocumentation
Clears the list of files with additional user documentation. After that new files can be added with the option "-u" or "--userdoc".
-f FILTERDEF, --messagefilter=FILTERDEF
Changes the filter for messages of the generator objects, filtered messages will not be shown after generating the documentation. This option is only relevant for the command line version.
FILTERDEF can be one or more sets of messages to filter, they are separated by the path separator of the current platform, this means semicolon ";" for Windows and colon ":" for Unix. Each set is defined as:
Filter ::= GroupName=([01][01]*|(+|-)number[,number]*|-)
The group name is generally the class the message is defined in. As can be seen there are three different possibilities to set the filter for the group. In the first version each message is represented by a binary digit, it will be filtered if its digit is "1". In the middle version the first plus or minus sign defines whether the messages, identified by their indices within the group and following as a comma separated list, should either be filtered "+" or not "-". When only a minus sign "-" is specified, all messages from the group will be shown. An example:
-f TFormatCommentDoc=+0,1,2,3,4,5,6,7;TJADDCommentEvaluator=-
-F, --clearmessagefilter
Clears the filter for messages of the generator objects, so all messages will be shown. This option is only relevant for the command line version.
-v TOPICS, --verbose=TOPICS
Specifies what topics the command line version should be verbose about, this option is ignored for the GUI version. If TOPICS is empty all topics are implied. Currently only three topics are available represented by the tree letters "P", "I" and "G". If a letter is in the value of TOPICS, the program will be verbose about its topic. The usage of the short option is recommended, as the long option will probably be changed to use longer names of the topics at some point in the future.
"P" indicates that the messages of the parser should be shown after parsing source files. "I" indicates that the list of "unknown" identifiers within the parsed source files should be shown after parsing. "G" finally indicates that the messages of the generator should be shown after generating the documentation. Please notice, that these can also be filtered on a per-message basis with the -f option.
-V TOPICS, --quiet[=TOPICS]
Specifies what topics the command line versions should remain quiet about, it is ignored in the GUI version. This option is the counterpart to -v/--verbose, it has the same meaning, only that the final list of topics to be verbose about will be inverted.
-r, --showprogress[=true|false]
Specifies that (whether) the progress of the parsing of source files and generating of documentation should be shown in the command line version, ignored for the GUI version.
-R, --hideprogress
Specifies that the progress of the parsing of source files and generating of documentation should not be shown in the command line version, the option is ignored for the GUI version. This can be handy when the output of the program is redirected into a file and it shouldn't be cluttered up with the progress bars.
The -a switch is no longer supported. It has been superseded by the option -A/--generate.
-i FILE, --guilogfile=FILE
Adds a log file of a GUI to generate documentation as a help about or a directory containing such log files to the internal list of log files.
-I, --clearguilogfiles
Clears the list of log files of GUIs of which help can be generated. After that new files can be added with the option "-i" or "--guilogfile".
-H FILE, --guihelpproject=FILE
Loads a GUI help project file defining the list of log files of GUIs to generate the help about and the alternative content of the main index for the help. After loading these information the current generator objects try to read their options from the file and localized versions of the texts are also loaded if available. Due to this, the generator objects should be selected before loading the project file.
-A, --generate[=MODE]
Generates documentation with the currently available data. The mode defines what kind of documentation should be generated.
"Source" is the default and will generate documentation about the parsed source code and include the additional user documentation. "UserDoc" will only use the files of user documentation when generating. "GUIHelp" will generate the documentation as a help on the GUI whose log files have been added and also include the additional user documentation.
When no mode is specified the most recently used mode will be used again, initially always documentation about source code is selected. In the command line version this switch is always implied as the last option when new data has been read or options been changed since the last generation.

Documentation Formats

At the moment there are five different formats to choose from: HTML, Windows Help file, HTML Help, LATEX and PDF.

The HTML-Format is the first and thus it is the oldest generator. It was the simplest format to generate but under Windows perhaps not the most comfortable to use. So there may be some things, that could be optimized or better formatted.
The Windows Help Format is really comfortable to use, if it is integrated in the help of Delphi, so you get help via pressing F1 directly in the IDE.
The HTML Help Format is the new help format in Windows. It is similar to the old format but raises its limits greatly so it can also be used for really big projects.
LATEX can be used to generate documents in many different formats. Created PDFs for example are linked (like HTML) and easy to use. The makros for these links can be changed to produce texts usable in printed versions.
PDF files (Portable Document Format, copyrighted by Adobe) look quite similar to the PDF files generated by the LATEX files but you save the compiling with TEX and, well, you don't have to have TEX installed.

Each generator creates also a few Xfig- (*.fig), WMF (*.wmf) and SVG-files (*.svg). These show the relations between files and classes/interfaces. XFig-Files are vector graphics, their format is textual not binary in contrast to WMF-files. The format originated from the Unix-world, but there are programs to view and edit these files for Windows. WMF-files should be insertable into most office-programs. SVG - Scalable Vector Graphics - is a open textual graphic format based on XML, it is an official W3C standard, most internet browsers should be able to show them without any problems. There are also lots of programs supporting the format, and for the Internet Explorer plug-ins are available to enabled also that browser to view SVG images.

The generators define serveral options. Please do use them, they allow the customization of the generated documentation and the parsing of your comments. New options may be added in future versions. Some of their options are available in all generators, some are specific to a generator.

The texts used in the documentation can be localized. In the GUI the button Localization will open a window to edit them. The last option can be used to load a file with saved texts, and the one above it to select a predefined translation. At the moment only "English" (the default) and "German"/"Deutsch" are available. The file can also be loaded or the language be selected with the parameter "-L" when starting the program.


If the documentation is generated in the format HTML (Hypertext Mark-Up Language) a lot of HTML-files will be created in the given directory. The index file is named index.html. This is obviously the simplest format to use, HTML is directly generated, no further processing is necessary, although with the introduction of the PDF generator it got a rival. Only a simple browser is needed. No frames are used, so the simplest browser will do. Most used tags are really old HTML so every browser will understand them. CSS is only used once to mark strings red, so the user may simply alter the CSS file to change this. A lot of HTML files will be created along with some images (*.gif or *.png) and one Cascading Style-Sheets file (DelphiDoc.css).

The CSS file contains also a few lines as a comment describing how to create other styles. The following classes are used within the generated HTML-files (HTML-attribute class=...):
abstract, additional, author, called, calls, class, classcomment, classtree, classtreefiles, classtreeunknown, example, examples, exception, exceptions, file, filecomment, filelist, filelistfiles, funclist, globals, headerlinks, ident, idents, identslist, identsscope, implements, included, includedlist, independentunits, index, longfunc, member, methodlist, overridden, overrides, param, params, project, result, see, special, string, unit, used, usedfilessub, usingfiles, usingfilessub, version
and some others.

Windows HTML Help

The new Windows help format with the file extension .chm is a compilation of HTML files, what exactly chm means is hard do tell, Compiled HTML Help or Compressed Help Module(s) or something inbetween or completely different. Well, anyway, as the names suggests its mainly an archive of lots of HTML and additional files like images.
I personally don't like the new format, it's somehow "laggy", and even Delphi uses the old .hlp format. And please be aware that the user who wants to view the generated help files needs to have the HTML Help viewer and Internet Explorer installed. Of course he will in most cases, but if you still target old Windows 95 machines they might have a problem. Also Mircosoft starts to generate HTML Help version 2 for Longhorn and their new programs, but there is no stand-alone compiler or even viewer for that format, it is only included in some of their newer programs (mostly .NET based). This is also the format Delphi .NET uses for its help (probably because Microsoft provides the .NET documentation in this format). At least this is what I gathered. And anyway, CHM is already obsolete again, in Vista MAML seems to be the new standard.

Like the generation of the old Windows Help files here only the source files are generated and Microsoft's compiler is used to generate the final help file. The HTML Help Workshop can be downloaded as a htmlhelp.exe free of charge from Microsoft. And may also be distributed in several SDKs. If it is installed and was started once the created file DelphiDoc.hhp will be associated and can directly be opened.
The compiling can be started by the third button or through the menu "File | Compile...". The file DelphiDoc.chm will be created. This can be done automatically but has to be enabled in the options of the generator. The path to the help compiler may be needed to be given, if not it will be searched. For this purpose it is checked whether the file of the help project is associated or if it can be found in the search path.

Windows Help Files

If the documentation is generated in the format WinHelp a help project (ini file format) and a RTF-file is created that can be compiled to a Windows help file by the Microsoft help compiler (included in the Microsoft Help Workshop). Besides the RTF file, a file with the content (.cnt) and the project file, defining how to compile the RTF file to a help file, and some bitmap (.bmp) files containing some small icons to mark identifiers are created.

The Microsoft Help Workshop can be downloaded free of charge from Microsoft, but is also on the Delphi-CD (or other SDKs) included, and may have been installed in the directory C:\Program Files\Borland\Delphi\Help\Tools. If it is installed and was started once the created file DelphiDoc.hpj will be associated and can directly be opened.
The compiling can be started by Save and Compile or just by commands to compile. The file DelphiDoc.hlp will be created. This can be done automatically but has to be enabled in the options of the generator. The path to the help compiler may be needed to be given, if not it will be searched. For this purpose it is checked if it is installed with Delphi, if the file of the help project is associated or if it can be found in the search path.

The compiled help file can be integrated in the help of Delphi. In the Delphi IDE chose in the menu "Help" the item "Customize..." or start the program OpenHelp C:\Program Files\Borland\Delphi\Bin\oh.exe and then with it open the project C:\Program Files\Borland\Delphi\Help\delphi.ohp.
After the activation of the tab Index the compiled help file can simply be added. After saving the project, help to the documented identifiers should be accessible in Delphi simply by F1 exactly like for all other identifiers of Delphi. Now the documentation of DelphiDoc itself is too big to be integrated in the index, but you can still integrate it in the tab Link and accessing the help via F1 will still work (else the index tab will be completly empty, not a good thing).
Attention: Before integrating the help file it should be renamed or the automatical start of the generated help file in DelphiDoc won't work correctly anymore. The integrated help file will be shown instead of the freshly generated one, nevertheless it can still be started manually. It seems the help files are cached by the name of the file or they are searched with search paths, what leads to problems with files with the same name.


If the documentation is generated in the format LATEX several .tex-files are created. TEX is a typesetting system, that can be used to build the documentation in a lot of different formats. These include PostScript to print it directly and PDF (Portable Document Format by Adobe) that can be viewed on many platforms portable for instance with Adobe's Acrobat Reader.

TEX (the Greek letters Tau, epsilon and Chi, i.e. correctly: "ΤεΧ") documents are interpreted, not just parsed, it is a language on its own, comparable with macro languages. It was developed by one of the gurus of computer science, Donald E. Knuth, especially also for mathematical and scientific articles. As a free and portable system (and software) it is used for printing books etc. but can also be used for instance to produce PDF files. While TEX provides an interpreter, several (macro) packages expanding the capabilites to a more comfortable level are available. The most spread package is LATEX by Leslie Lamport. This package is also used for the generated documentation.

To generate these formats the LATEX-system is needed. You can download it free of charge on the web, take a look at the following pages: the Latex-Project, the (a) TeX Users Group and the the Comprehensive TeX Archive Network.
Just execute latex with the generated main file DelphiDoc.tex. Several macros/commands are defined in it, you may want or need to change them.

This generator has some shortcomings now. Images are not supported, so also documentation cannot be generated as a help on a GUI. This is due I don't know how to use portable graphic formats that can be used in LATEX in general (PDF likes JPEG or PNG, dvi wants eps (Encapsulated PostScript)). Also I don't know how to create links on images or parts of images. If anyone knows, I'd be glad to learn.

PDF - Portable Document Format

If the documentation is generated in the format PDF one single (and big) PDF file is created.
PDF means Portable Document Format; it is an open format copyrighted by Adobe. Read more about this format on their website. PDF files can be viewed on several platforms with different viewers. The best known is of course Adobe's Acrobat Reader. The used version of PDF is 1.2 (current: 1.6), that is quite old and it can be read with Acrobat Reader Version 3.x (current: 8) (at least it should). The old version of the PDF standard was chosen to allow maximum compatibility with other programs, and the important features for simple, read-only PDF files were all already defined in this old standard.

XMI - XML Metadata Interchange - UML export

XMI is a format based on XML that can be used to exchange UML data between UML design programs.
The created XMI files can be imported in at least ArgoUML, a free Java based UML tool. With XML as an open, standardized and easy to read format it is also possible to convert it to other formats or extract the information needed. But be aware that XMI/UML only knows classes, so any not object-oriented information is lost.
To convert XML files another powerful format, XSL/XSLT, has been created. There are a lot of XML libraries out there that can be used to convert the XMI file with an XSL file. Web browser can also use XSL files to show XML files, a simple XSL file will be extracted by default, at least Mozilla can use it to show the XMI file with links etc. (I've never used XSL before, so the code of the XSL file is not that good nor fast (DelphiDoc's XMI takes about 2 minutes to render in Mozilla), if you want an example that looks good, load ESS Model).