CODE Documentation creation tool for Delphi

Question

Possible Duplicate:
Code documentation for delphi similar to javadoc or c# xml doc

I want to start documenting a very large Delphi application, which currently has no documentation whatsoever. My coworker suggested a javadoc type documentation style because we can then run an automated program to create nice documentation which is searchable and looks pretty.

(* Description of the function            
 @param S        some string
 @param Index    the index of string s
 @retval TRUE    condition where it is true
 @retval FALSE   otherwise.
 @see            IndexOf
 @see            Sort
 @see            Sorted
*)
bool Stringlist::Find(const char *S, int &Index)
{
   [...]
}

Is this the best way I can accomplish meaningfull documentation for my project? If so what is a good program to handle these types of comments . So far I have had Doc-O-Matic recommended to me.

If it is any use the program is very old, it has been constantly developed since 1993 or so and has gone though many different authors, many different styles, IDEs, standards, etc.

Answer 1

Take a look at SynProject, an Open Source tool written in Delphi.

It was designed to handle a full documentation workflow, from specifications to release notes, including tests, architecture and design; and of course there is an integrated Delphi parser to generate architecture documentation from existing Delphi source code.

For the architecture document, the source code can extract comments (ala JavaDoc) then embed this text into the main Architecture document (with class hierarchy diagrams and unit dependencies).

You write a plain text file using a wiki-like syntax in a dedicated text editor, then SynProject creates well formated Word documents from it. Some Wizards are available to access the content. But since it's stored as plain file, multiple programmers can write on it, using any SCM tool (SVN, Fossil...).

For instance, I currently use it for writing maintenance documentation for a huge and old Delphi application (about 2,000,000 lines of code written in Delphi 5 and 6), with no prior available documentation. You describe the changes made to the code (by quoting the unit/class/method), then the tool will update all documentations to reflect and trace those modifications. SynProject was designed to be compliant with some very "delicate" regulation rules (IEC 62304), but can be used for any project due to its unique "flat" design.

Answer 2

There are no "best ways" for creating in-source documentation. Consequently, any answer will be subjective to some extent.

First of all you must choose your in-source documenting style. You can use either "native" comments, JavaDoc or XMLDoc. After choosing the documenting style you should choose the documenting standards.

Also you need a documentation generator to publish your in-source documentation (in html, pdf or other format)

As for Delphi source code, currently JavaDoc style is the most supported. I tried DelphiCodeToDoc (it uses JavaDoc) to generate html documentation, and it works. I think you can find more documentation generators for Delphi sources supporting JavaDoc.

Still I prefer XMLDoc style and Delphi Documentation Guidelines. That is subjective. I assume that the best XMLDoc Delphi documentation generator now is Doc-O-Matic. It also supports JavaDoc style, I am currently experimenting with it. It does not support all the tags mentioned in Delphi Documentation Guidelines, for example it does not support <list> tag, but you can use <para> instead and generate respectable documentation.

Try what is available and choose what you like more.

Answer 3

If you just want to document your source code based on functions comments, I would recomend you to use Doc-O-Matic.

But the real question here is: should you document your source code? I dont think so. According to TDD and XP, you should not comment your code at all. Your code should contains good procedures names that really indicates what the procedure does. So you could consider not document it, just refactor it so it can be easily understandable.