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


Eine deutsche Version ist ebenfalls verfügbar (veraltet, teilweise unvollständig).

JADD - Just Another DelphiDoc

To download DelphiDoc please go to the page of this project in the section of released Files.
You can also monitor the project to get an e-mail when a new version is released.


Fight Software Patents to bolster free software and
to make sure innovation will still stand for new ideas, and not for protecting old ones!
This is also the case in the USA and everywhere!

Table of Contents

There is a little survey about DelphiDoc, you can also watch the result of it.

Latest News/Changes on DelphiDoc

And again welcome to a new release.
Not that much new in this one, and most of the changes can be summed up with only two words: "image formats".

Support for other image formats has been added in several places. The inline command ~[image ] now supports images in all registered graphic formats, but the file extension has to be included in the file name for that, if none is specified ".bmp" is still the default. Supported are besides .bmp (Bitmap) also .ico (Icon), .wmf (Windows Metafile), .emf (Enhanced Metafile), .png (Portable Network Graphic), and .jpg (JPEGs in the JFIF format). Additionally the HTML generators also blindly copy files with extension .gif (Graphics Interchange Format), .svg (Scalable Vector Graphics), .svgz (compressed SVGs) and .mng (Multiple-Image Network Graphics).

The images will not be re-converted if possible. This may actually lead to some problems, for instance the PDF generator has some limitations in handling PNG files (no alpha channel (without palette), no interlace, must use zlib for compression, only 8-bits per color component), the alpha channel is probably the only one ever raising any problems, so it has to be removed before including the file via a PDF generator. Gamma information and transparency information is lost in any case. And I don't know how JPEG data in other file formats (like Exif or SPIFF) will be handled. You might want to recompile DelphiDoc with another JPEG library then that one shipping with Delphi.

Potential problems with images with the same name in different directories have also been fixed by creating unique names for the images.

The screen shots of forms to be used to generate help about the forms can now also be in other formats. The file extension has just to be specified with the option "GUIScreenShotExtension" in category "GUIHelp" of the scanner of comments (has to be edited with all options of all objects for the generation for the time being), probably the main advantage is just to save some HDD storage space after converting the huge bitmaps to PNG.
The form to create the GUI log files and screen (window) shots also got an option to save directly as PNG files, if you don't have or don't want to use the unit "pngimage" in your project to support these PNG images, you just have to comment out a define for conditional compiling in the uses clause in the interface of the unit.

The external files showing the inter-dependence between the files and the inheritance tree of classes and interfaces can now also be generated as SVG (Scalable Vector Graphics) images. SVG is an open, textual (XML-based) standard by the W3C, it can be viewed directly with most internet browsers, the most notable exception being the Internet Explorer, which needs a plug-in, like the Adobe SVG Viewer.
For this output several new texts to be localized have been defined:
"DocumentationLinkGetSVG1", "DocumentationLinkGetSVG2", "DocumentationLinkSVGFiles", "ErrorSVGFileLinkHeader", "ErrorSVGFileLink1", "ErrorSVGFileLink2", "ErrorSVGFileLink3Pre", "ErrorSVGFileLink3Post", "ErrorSVGFileLink4Pre", "ErrorSVGFileLink4Middle", "ErrorSVGFileLink4Post", "ErrorSVGFileLink5", "ErrorSVGFileLink6"
The formats to be generated are now selected via the option "GenerateFileAndClassesTreeFormats", which is a set and replaces the previous two boolean options. If the documentation is generated in an HTML format, links will be included in the SVG file directly to the documentation of the files and classes, this can also be disabled via the option "GenerateFileAndClassesTreeSVGWithLinks".
Windows Meta Files (.wmf) of these images are now also saved instead as Enhanced Windows Meta Files (.emf).

Diagrams can also now be exported as EMF (and WMF) and SVG. The SVG files can also contain direct links to the documentation in HTML format. They can also be compressed (.svgz). The diagram generator got the options "ExportImageType" and "CharacterEncoding" for this, but the format can more easily be selected by using the appropriate file extension in the file name.

When generating documentation in one of the HTML formats the diagrams created via the inline command ~[diagram ] can be saved as Scalable Vector Graphics. The format can be set via the new option "HTMLDiagramFormat" - PNG is still the default, and compressed SVGs are possible, too. The SVG files also contain the links to the documentation of the classes and files in the diagrams themselves rather than the HTML file showing them, this can be disabled via the option "SVGDiagramsWithLinks", but that will probably not be a good idea.
Sadly the results are not that promising in my tests yet, but I don't have the newest versions of some softwares, so you should probably test it yourself. Compressed SVGs are shown especially wrongly, Mozilla and Opera don't recognize the compression for local files and try to parse the compressed stream as an XML file, which of course fails miserably. But even without compression the files still have a decent size. Adobe's SVG Viewer plug-in for the Internet Explorer (and Netscape) shines here again, although it can't show SVG images with a character encoding "Latin-1" (maybe only "UTF-8"). Also the images are included via iframes, which may make them less compatible with some (older) browsers. I'm happy about any feedback about this feature.

Similarily when using ~[diagram ] in PDF output, the diagrams will now be drawn directly in PDF and not be included as an image. They can still be rendered as PNG images if the option "DiagramsDirectlyAsPDF" is disabled, see there for a discussion of the advantages of not doing that.

So much for the images and their formats. And now for something completely different.

As the options of the generator objects grow more important and numerous with each release, the main form to edit them has been improved somewhat in this release. A small dialog to search options and a component showing the documentation from the HTML documentation have been added.

And as promised in the last release it is now possible to use the inline commands ~p, ~br and ~inheritDoc without the following brackets []. This can be disabled via the option "OptionalCommandParameterBraces", but that is probably only needed if the option "ParamNamesAsSections" is used. This is another step towards better Javadoc-compatibility, although it doesn't probably matter until @true, @false and @nil/@null are defined.

Generating help on forms without a help context no longer aborts the generation with an assertion failure. The generators should use less memory while generating (at least for now, might change in a few releases when new features are added again, which will need the memory). The old frame to show the messages of the generators has been added again to be used with Kylix, and it compiles again after applying the usual changes. And also as always my warning, the old generators will soon vanish, and they haven't been tested for several releases, so please use and test the new ones. And finally thanks to 明保 王 for pointing out an error in the code handling the hiding of scroll bars in read-only memos when they are not needed.

Pre-Pre-Pre-Pre-Previous News (New Concept for Generators)

The new generators are about 25% slower than the old ones and they should also need significant more memory, because all comments will be parsed first and held in it. But they should parse the comments in a much cleaner way and also generate a much cleaner documentation. They also have more power in evaluating the information inside the comments, so new functionality can be added that was not possible in the old system (like excluding identifiers based on their comment or grouping identifiers of special topics together).
The new system also uses more objects, the options of those can currently only be edited with the button on the same page as the button to generate the documentation, i.e. with all available options in one big list (tree view). But luckily, as you should know, the list can be filtered for each class.

There is a quote out there (from Butler Lampson or David Wheeler):
All problems in computer science can be solved by another level of indirection. (often misquoted with "abstraction")
And, well ..., in anticipation of further problems I readily introduced several layers of abstraction. Surprisingly it does not seem that much slower, only about a quarter, but well, I guess, string handling is slower than I thought.

Btw., if you don't see quotes around the above quotation, you are using a browser that doesn't comply to a nine year old standard and the very base of the World Wide Web, as:

Visual user agents must ensure that the content of the Q element is rendered with delimiting quotation marks.

Requests

Any feedback on DelphiDoc is welcome. Especially also on the different character encodings. In HTML you can set you own encoding in the options. But I don't know what has to be done in Windows help files, LATEX files and PDF files to choose the correct encoding/font, mainly because I'm so fortunate to use a language where the default encodings (Latin-1/Windows-1252/ISO-8859-15) suffice.

Feedback on parsing of the comments would also be appreciated. I know that no one has projects commented for this program, beside this one. But even generating the documentation with the options DoNotSectionize and DontParseComments enabled the comments (I hope most projects will have at least some kind of a comment) should be valuable, so I hope they are correctly found.
So any feedback on how these comments are inserted are welcome, i.e. "Are they actually found by DelphiDoc?", "Are there any special characters/words/lines that are not really part of the comment and should be removed?" or "Are there any errors with any special characters?" and so on.

Some basic statistics are gathered about the parsed source code, you can view them in the form with the source code (F9). These values are currently not saved and not included in the documentation. I'm actually thinking about how, when and whether to include it somewhere in the documentation and also what other statistics to gather. You have some suggestions?

You may have noticed there is still something below the TOC (Table of Contents) on the home page, yes, I started a little ongoing survey. So if you want to tell me and anyone looking at the result how you use Delphi and what you need, there is your possibility. It consists simply of several questions with yes/no/maybe - radio buttons. Answering them will only increase the corresponding counters, so don't expect anything special.

What is DelphiDoc?

DelphiDoc is a program for automatic generation of documentation on a Delphi-Project. It is created with Javadoc in the mind, i.e. what Javadoc does for Java DelphiDoc should do for Delphi but better fitting to it.

So the documentation is not limited to the HTML format, because in Delphi and Windows the Windows Help format and the new HTML Help are more common, and Windows Help files can be integrated in Delphi's IDE for easy accessibility. As the special character in the comments the tilde "~" has been chosen instead of at "@", because the at-symbol is used in the Pascal language, the tilde is not. But this character can also be redefined to any other. At the moment the documentation can be generated in the HTML (HyperText Markup Language) format, in the Windows help (.hlp-files) format and the new HTML Help format, in the LATEX format or in PDF (Portable Document Format by Adobe) with some additional xfig-/wmf-files. Export to XMI to be used in UML-modelling tools is also possible, and last but not least it is also possible to generate diagrams (UML-like) of the parsed classes etc. and even to include them directly in the documentation.

DelphiDoc's distinctive features are an extensive parsing of the source code and a division of the parser and the generator of the documentation, and there are also a lot of options to tweak the generation. The first means a lot of information is gathered and can be inserted in the documentation making it valuable even if there are no comments (really useful to get acquainted with unknown projects if the generated help file is integrated in that of Delphi). Very much links are inserted as a cross-reference leading from identifiers to other identifiers if they use each other.
The second leads to exchangeable generators for documentation. At the moment five generators can be chosen to create the documentation in the above mentioned formats. Some additional generators for special things are also available. The several options of the generators and "inline command"s inside the documentation make these even more powerful.

The documentation is somehow focused on an object-oriented design, so on purely not object-oriented programs the generated documentation may be not that efficient/well structured.

How compatible is DelphiDoc with Delphi 8+/.NET?

DelphiDoc does not support .NET currently. Delphi 2005 for Win32 is also not fully supported, yet. Some features have been implemented, but without enough information available it is hard to implement everything save (the Delphi-compiler is the only true grammar of the language and I don't have it). There is a limited support for unit-namespaces. The new scopes "strict protected" and "strict private" are parsed, but the scope is only treated as the normal scopes without the "strict". Multicast eventhandlers (properties) with the attributes "add" and "remove" can now be parsed. The "for ... in ... do" can also be parsed.
Not supported are nested types, class constants and the file-namespaces only partially. This is mostly due to insufficient information, so any hints on this behalf would be helpfull.
Unicode source files will also not be parsed, while UTF-8 should be no problem. Although when generating some generators may corrupt the UTF-8 comments and for others you may need to set the character encoding.

Support for .NET will not be added in the near future. There are not enough information about it available and the changes to the language are quite extensive. Still some changes were made in that direction (removing Delphi 3 as a possible platform to compile DelphiDoc). Any concrete, detailed information about it would be helpful.

What do I have to expect when using Kylix?

Most changes on the binary are how you expect them. No generated documentation will be launched automatically after generation because there is no associated binary to launch them. Also Window help files are not automatically compiled (what a surprise), although it is possible to compile them with the help of Wine. And no WMF (Windows Meta File) files are created (WMF records GDI calls, of course there is no Windows GDI in *nix).
Symlinks of directories are not followed (is that even possible?) to avoid eternal recursion (or until the stack if full), but the symlinks may be defined by them self, that should work. Furthermore the wrong end-of-line character sequence may be used sometimes, i.e. #13#10 instead of just #10, but that should never invalidate any file.
If you want to compile DelphiDoc under Kylix take a look at the notes about the source code.

Main Issues

DelphiDoc does not support .NET currently. Delphi 2005 for Win32 is also not fully supported, yet. Unicode source files will also not be parsed, while UTF-8 should be no problem. Although when generating some generators may corrupt the UTF-8 comments and for others you may need to set the character encoding.

Legal Stuff

This program is now distributed under the GPL - the GNU General Public License version 3. A copy of the GPL should accompany the release in the file "LICENSE.txt". Please also take a look in the file "README.txt" for the used libraries, that are part of this program (and release) and are distributed with other licenses.

And a note on the generated documentation:
The generated documentation inherits its legal status from the source (code) it was generated from, i.e. if you wrote the source and DelphiDoc generates some documentation, you also have the copyright on the documentation like on the source.

Contact

For questions, suggestions and so I would prefer if you use one of SourceForge's services like the Forums, the Trackers, the Mailing List or the private message facilities there.
So far I can also be reached through email at DelphiDoc @ gmx.de (sorry for not making a link for it, but I don't want to serve up another email address for spam on a plate for web crawlers, ... I get enough already), just be sure to use a meaningful subject for the mail so it won't get lost in all the spam I get, please include "JADD" or "DelphiDoc" in the subject, using a plain text mail (instead of HTML) will also decrease that chance.

DelphiDoc should be able to parse most of the correct and compilable programs, but there are some constructs that may raise problems (it's weird what's all possible in Delphi and then gets compiled). In most cases the line and column should be given when an error occurs during the parsing, of course, just like with the real compiler, the true reason of the error may be a few lines higher.

Should an error occur, a description of the error and a relevant excerpt of the source code, or of the whole project in case of complex constructs, can be send to me by email.

Best regards,
   Gerold Veith

This page has been found at http://delphidoc.sourceforge.net/.

Last change: Saturday, the 5th April 2008, 15:00 GMT +0100; Page created with Delphi-Text-Editor; Optimized for HTML 4.01 Transitional