Project-Page: http://sourceforge.net/projects/delphidoc/
Homepage: http://delphidoc.sourceforge.net/
Project-Page: http://sourceforge.net/projects/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.
There is a little survey about DelphiDoc, you can also watch the result of it.
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.
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.
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.
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.
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.
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.
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.
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.
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