Project-Page: http://sourceforge.net/projects/delphidoc/
Homepage: http://delphidoc.sourceforge.net/
Project-Page: http://sourceforge.net/projects/delphidoc/
Nothing so far.
Nothing so far.
Nothing so far.
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.
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.