Board index » delphi » Re: JavaDoc vs. XMLDoc

Re: JavaDoc vs. XMLDoc


2007-05-23 06:07:08 AM
delphi81
"Kyle A. Miller" <XXXX@XXXXX.COM>writes
Quote
Which have you chosen and why? Which tool do you use to
produce documentation from those comments?
XMLDoc support is built into BDS, sort of. The Delphi compiler has a
new -doc command-line flag available that generates XMLDoc output
files while compiling the code. You can then run them through your
favorite XMLDoc parser afterwards. If you look around BDN, I think
there is a beta parser floating around (it based on Python scripts, so
you need to install Python separately) that can generate
human-consumable documentation from the XMLDoc files.
Gambit
 
 

Re: JavaDoc vs. XMLDoc

Where do you guys find time to investigate and learn about these things ...
I'm over here coding my {*word*82}off ...
I must be 30 years behind times ...
 

Re: JavaDoc vs. XMLDoc

When using Delphi or VStudio, I use XMDoc. When using Java, I shoot myself
in the face: www.killnine.com/comics/7.php
"Kyle A. Miller" <XXXX@XXXXX.COM>writes
Quote
There seems to be two common source code documentation formats, JavaDoc
and XMLDoc. I like JavaDoc's readability, but XMLDoc is very popular
because of VS' support. XMLDoc has a lot of punctuation "noise." I don't
want to invest time choosing one syntax only to find out the other is
trumping one I chose in support.

Which have you chosen and why? Which tool do you use to produce
documentation from those comments?
 

Re: JavaDoc vs. XMLDoc

Del Murray writes:
Quote
Where do you guys find time to investigate and learn about these things ...
I'm over here coding my {*word*82}off ...
I must be 30 years behind times ...
I have been very busy too. it is writing all of this code that reminded
me of the importance of leaving some documentation for the next guy. And
since every keystroke counts, I figure if I am going to enter comments
for the next guy, why not put it in a productive form? Then, I remember
Delphi supports XmlDoc, and I also remembered there being a free JavaDoc
tool (DelphiCodeToDoc. There's also DelphiDoc.). Thus my quest began. I
found a number of threads in Google groups, but no one received a
satisfactory answer to what I am asking here.
The general feel my research so far is "Go with XMLDoc and Doc-o-Matic."
Doc-o-Matic is a nice tool, but I feel overpriced. GenHelp Pro is a
bit more reasonable and supports XmlDoc and JavaDoc. It just seems in
the Delphi world, JavaDoc or JavaDoc-like has more support.
The more I think about it, the more I think I will work with XmlDoc and
GenHelp Pro. A free accessory for this combo is Ingvarius DelphiComments
tool. Thanks Ingvar Nilsen!
 

Re: JavaDoc vs. XMLDoc

Don Strenczewilk writes:
Quote
When using Delphi or VStudio, I use XMDoc. When using Java, I shoot myself
in the face: www.killnine.com/comics/7.php
:-)) Wow. That seems extreme.
Thanks for your input!
 

Re: JavaDoc vs. XMLDoc

Hello,
maybe another thing worth to look at is DelphiCodeToDoc, available at
sourceforge. It generates a HTML help or HTML pages out of a JavaDoc
like commented source.
Greetings
Markus
 

Re: JavaDoc vs. XMLDoc

"Kyle A. Miller" <XXXX@XXXXX.COM>writes
Quote
Del Murray writes:
>Where do you guys find time to investigate and learn about these things
>... I am over here coding my {*word*82}off ...
>I must be 30 years behind times ...

I have been very busy too. it is writing all of this code that reminded me
of the importance of leaving some documentation for the next guy. And
since every keystroke counts, I figure if I am going to enter comments for
the next guy, why not put it in a productive form? Then, I remember Delphi
supports XmlDoc, and I also remembered there being a free JavaDoc tool
(DelphiCodeToDoc. There's also DelphiDoc.). Thus my quest began. I found a
number of threads in Google groups, but no one received a satisfactory
answer to what I am asking here.

The general feel my research so far is "Go with XMLDoc and Doc-o-Matic."
Doc-o-Matic is a nice tool, but I feel overpriced. GenHelp Pro is a bit
more reasonable and supports XmlDoc and JavaDoc. It just seems in the
Delphi world, JavaDoc or JavaDoc-like has more support.

The more I think about it, the more I think I will work with XmlDoc and
GenHelp Pro. A free accessory for this combo is Ingvarius DelphiComments
tool. Thanks Ingvar Nilsen!
I'll put in a vote for DelphiCodeToDoc. While not perfect, the nice thing is
that you don't need more than one tool to get the end-result, a nice html
help file.
Antti Kurenniemi
 

Re: JavaDoc vs. XMLDoc

Quote
Which have you chosen and why? Which tool do you use to produce
documentation from those comments?
XML Doc and then run the results through SandCasle.... though that might
make C# like docs... still readable though.
 

Re: JavaDoc vs. XMLDoc

M.E. writes:
Quote
XML Doc and then run the results through SandCasle.... though that might
make C# like docs... still readable though.
Does SandCastle work with .NET assemblies only? Or will it process the
XmlDoc file Delphi produces? .NET and Win32?
 

Re: JavaDoc vs. XMLDoc

[snip]
Quote

I'll put in a vote for DelphiCodeToDoc. While not perfect, the nice thing is
that you don't need more than one tool to get the end-result, a nice html
help file.
Yes and the best: beta 0.17 also has metrics now.
But I would like to have some option to not list any labels on forms etc.
which don't have a comment. Or does anybody comment such labels etc. as
well? Only in special cases afaik.
Greetings
Markus
 

Re: JavaDoc vs. XMLDoc

Markus.Humm writes:
Quote
Yes and the best: beta 0.17 also has metrics now.
But I would like to have some option to not list any labels on forms etc.
which don't have a comment. Or does anybody comment such labels etc. as
well? Only in special cases afaik.
Anyone tried PasDoc/PasDOCGUI ?
It seems more powerful than DelphiCodeToDoc (knows way more tags) and
also has formatting tags such as @bold, @italicetcetera. It even lets you
embed tables. I have used it in one project (when I still had time to do
thorough documentation...)
--
Arthur Hoornweg
(In order to reply per e-mail, please just remove the ".net"
from my e-mail address. Leave the rest of the address intact
including the "antispam" part. I had to take this measure to
counteract unsollicited mail.)
 

Re: JavaDoc vs. XMLDoc

Hello,
you can embedd other thjings with CodeToDoc as well, if you allow HTML
inside the comments and use that for formatting.
Greetings
Markus
 

Re: JavaDoc vs. XMLDoc

Hello!
I am still at Delphi 7 but am considering upgrading to Delphi 2007. I would
like to prepare a migration of my comments written for DelphiCodeToDoc to
XMLDoc but is this possible? I guess what I am asking is if it is possible to
change the syntax of my comments in DelphiCodeToDoc to fit that of XMLDoc or
will I have to start all over?
Where can I find a complete description of the syntax of XMLDoc comments?
Regards,
Erik
"Markus.Humm" <XXXX@XXXXX.COM>skrev i en meddelelse
Quote
[snip]
>
>I'll put in a vote for DelphiCodeToDoc. While not perfect, the nice thing
>is that you don't need more than one tool to get the end-result, a nice
>html help file.

Yes and the best: beta 0.17 also has metrics now.
But I would like to have some option to not list any labels on forms etc.
which don't have a comment. Or does anybody comment such labels etc. as
well? Only in special cases afaik.

Greetings

Markus
 

Re: JavaDoc vs. XMLDoc

Erik F. Andersen writes:
Quote
Hello!
Hi! I am not Markus, but I will throw my $.02 in. :-)
Quote
I am still at Delphi 7 but am considering upgrading to Delphi 2007. I would
like to prepare a migration of my comments written for DelphiCodeToDoc to
XMLDoc but is this possible? I guess what I am asking is if it is possible to
change the syntax of my comments in DelphiCodeToDoc to fit that of XMLDoc or
will I have to start all over?
As I understand, DelphiCodeToDoc uses JavaDoc syntax. So, if you used
JavaDoc syntax, you won't have to change it if you use tools like
Doc-O-Matic or GenHelp Pro. They can read both.
Of course, you will want to migrate all of your comments to one style in
time. A tool which might be helpful in this regard, unless an automated
one exists, is Ingvarius DelphiComments. It gives you one easy to use
window to edit the comments in a unit. it is free. You can try it out.
www.ingvarius.com/products/delphicomments/Default.aspx
Quote
Where can I find a complete description of the syntax of XMLDoc comments?
Searching on XMLDoc will produce a lot of false positives with Google.
Search on "XML Documentation Comments"
 

Re: JavaDoc vs. XMLDoc

Thanks,
just one more question though. Is XMLDoc output supported in the
professional version of Delphi 2007 Win32?
Regards,
Erik
"Kyle A. Miller" <XXXX@XXXXX.COM>skrev i en meddelelse
Quote
Erik F. Andersen writes:
>Hello!

Hi! I am not Markus, but I will throw my $.02 in. :-)

>I am still at Delphi 7 but am considering upgrading to Delphi 2007. I
>would like to prepare a migration of my comments written for
>DelphiCodeToDoc to XMLDoc but is this possible? I guess what I am asking
>is if it is possible to change the syntax of my comments in
>DelphiCodeToDoc to fit that of XMLDoc or will I have to start all over?

As I understand, DelphiCodeToDoc uses JavaDoc syntax. So, if you used
JavaDoc syntax, you won't have to change it if you use tools like
Doc-O-Matic or GenHelp Pro. They can read both.

Of course, you will want to migrate all of your comments to one style in
time. A tool which might be helpful in this regard, unless an automated
one exists, is Ingvarius DelphiComments. It gives you one easy to use
window to edit the comments in a unit. it is free. You can try it out.
www.ingvarius.com/products/delphicomments/Default.aspx

>Where can I find a complete description of the syntax of XMLDoc comments?

Searching on XMLDoc will produce a lot of false positives with Google.
Search on "XML Documentation Comments"