SourceForge.net Logo Homepage: http://delphidoc.sourceforge.net/
Project-Page: http://sourceforge.net/projects/delphidoc/


JADD - Just Another DelphiDoc

FAQ - Frequently Asked Questions

This FAQ has just been started and doesn't contain much, you're welcome to ask some question to let them be added to the FAQ.

Table of Contents

General

Nothing so far.

Parser

Nothing so far.

Documentation

Nothing so far.

Comments

How to extract comments?

Comments are always taken from directly above the declaration of an identifier and from the same line. For files it is the first comment in it. There are several options in the extractor to modify the extraction.
For files you can also use the first comment after the first statement, allowing to skip copyright-notices etc.. Similar you can indicate if the comments should be extracted from the first (forward-) declaration or the final one. To extract the content of comments and skip useless separators you can remove all leading and trailing stars "*" or even use powerful Regular Expressions. Instead of stars also other markers can be used.
The other objects contain further options to change the handling of the comments, so be sure to also read through them.

DelphiDoc supports a range of sections and commands in comments. You can define the special characters (using for instance "@" instead of "~" like in similar tools) and also rename sections. You can also disable the parsing of comments and just insert them as-is, or even ignore comments completely and just generate the cross-references with DelphiDoc.

If that isn't enough for you, or just your comments are at a complete different position (even outside the source-code, like in an ini-file or data base) you may want to change DelphiDoc and compile it yourself. In that case take a look in the file \Generator\CommentHelper\USourceCommentExtraction.pas at the class TSourceCommentExtractor. You can either change the two methods Comment and CommentOfFile or create a new sub class and override them.

TOC

Miscellaneous

Do you know any other/similar tools like DelphiDoc?

There are several other tools that are more or less similar to DelphiDoc, I'm by far not the first that had the idea. But at the time I started to write DelphiDoc there were not other free tools that would satisfy my needs. It's getting better, but as far as I know there is still no program that would provide all needed features. But, well, of course the own program written for the own needs always fits the best. And my "needs" are also not that important because I used DelphiDoc really only once, and that was in spring 2003 only a few month after I started programming it, only to document my program for the intermediate diploma at the University of Applied Sciences Wedel.

The main problem of most programs still seems to be, they are to close to the original JavaDoc and only generate HTML, well, and slightly changed that to also compile it to HTML Help. If that is what you want: no problem, if you want another format you've got a problem. Another thing may be the parsing of the source code. That again depends on what you want and need. Simply listing all identifers in the source should be no problem. DelphiDoc parses the source like the compiler, so it has additional information for an extensive cross-reference, like used identifers etc., but it also means, that identifiers, that are not compiled due to conditional compiling, won't be documented. In both ways you might have a piece of source code that can't correctly be parsed by one of the programs.

As said, it all depends on what you want. Best thing is just to try the different programs and their options and see which fits best.

DelphiCodeToDoc
This is a nice program that wasn't around when I started. Maybe if it had, I wouldn't have written DelphiDoc.
The GUI of the program is about a million times nicer than the old one of DelphiDoc (but I had a progress window :-P), but now I hope I narrowed the gap considerably with the new GUI. But on the other hand, DelphiCodeToDoc has far less options to squeeze onto a form. Its GUI can use several different languages, but the documentation itself is still fixed on english. The documentation can also only be generated in HTML and, recently added, HTML Help. The program seems now about to leave the beta phase, it can for example almostly parse DelphiDoc's source (and does now also give positions of the errors!).
Still a nice project that should be tracked.
DelphiDoc (SoftConsult)
This is also very nice project, the best I found before I started. Sadly even with my other program it got errors. And it's closed source and it seems not further developed, so I couldn't fix it. But its free, and regulary you will find it searching for something like DelphiDoc, so you won't miss it in this list.
DelphiDoc (Soletta)
This is a different story. This DelphiDoc wasn't free, you had to pay for it (IIRC the first versions had been free). Nowadays it's not further developed, and it seems the creator lost the source. But searching for DelphiDoc you will find the name Soletta everywhere, mainly to download the evaluation version from very out-dated shareware services.
PasDoc / DIPasDoc
Not the most active projects, but probably one of the oldest. As the name implies not only for Delphi but for other dialects of Pascal, too. Exports to HTML, HTMLHelp and (again) LATEX, supports generating RTF files from the LaTeX output.
Pro-Analyzer
This is not a documentation tool, but an analyzer. It generates detailed reports about the source code. Something you won't find anywhere else, but that doesn't come for free. And some of the reports are also obsolete because the Delphi compiler does its tests automatically.
ESS Model
This is also not a documentation tool, but an UML reversing tool for Delphi and Java. Once a commercial product it was released with source for free (as in speech, i.e. the GPL). It parses the source code and generates UML diagrams from it. It can also export the UML model in an XMI file that can be read by ArgoUML, a Java-based open-source UML-tools. I was very impressed by this tool, what led me to implementing these both key features also in this DelphiDoc. This project is also no longer actively developed.

TOC