Which autodoc tool?

I have been charged with determining a standard for my company for
finding a standard for documenting our code. Actually, I'm new to the
company and have been told that very little is generated so I get to
determine what documentation is acceptable before the current employees
transfer within the company. This means that whatever standard I pick,
I have to be willing to accept the output and then maintain it so my
successor as well.

80~90% of our code is PHP with the remaining balance in Perl. Tools I
have considered so far are:

CHOICE 1: PHPDOC at http://www.phpdoc.de
The original? appears like stagnated several years ago and never grew.
Not really giving it serious consideration unless someone has
compelling reasons otherwise.

CHOICE 2: PHPDocumentor at http://phpdoc.org
What can I say except it appears to the one of the most recommended
tools I have found in research. I am unsure what to expect from it
compared to my third choice.

CHOICE 3: DOXYGEN at http://www.doxygen.org
Been around a long time and doesn't seem like a bad choice. It just
doesn't have the same emphasis on PHP that PHPDocumentor does.

Some of the key points I am looking at personally include:
1) Long term viability of the solution chosen. This could be offset by
the compatibility of the tags with other products.
2) Ease to get existing code documented to the chosen standard
3) Ease to document future code
4) Quality/flexability of the tool chosen

Anyway, which opensource documentation tool do you recommend and why?
Please indicate in responses which you have experience with.

Thanks in advance for the opinions!
Anthony

anthony,

> Some of the key points I am looking at personally include:
> 1) Long term viability of the solution chosen. This could be offset by
> the compatibility of the tags with other products.
> 2) Ease to get existing code documented to the chosen standard
> 3) Ease to document future code
> 4) Quality/flexability of the tool chosen
>
> Anyway, which opensource documentation tool do you recommend and why?
> Please indicate in responses which you have experience with.

Personally I use PHPDocumentor. One because of the support it has with
the tags alone are normally far better than the others. The tags itself
works with the svn/cvs tags as well ie (@version).

The ease of using PHPDocumentor is insanely easy. Although it may take
a little bit to actually get used to it and understand it as most
documenting programs do, but if you are at all familiar with JavaDoc you
will run right into it fine.

To document future code is extremely easy, and even if you deprecate a
function there are tags for that as well! Also tags to show that this
function was available since a certain date.

The quality and flexibility in my mind is amazing, there is only one
thing more that I want is to be able to have inline code examples
generated if more than one exists.

Mike

Mike Willbanks wrote:

> anthony,
>
>> Some of the key points I am looking at personally include:
>> 1) Long term viability of the solution chosen. This could be offset
>> by the compatibility of the tags with other products.
>> 2) Ease to get existing code documented to the chosen standard
>> 3) Ease to document future code
>> 4) Quality/flexability of the tool chosen
>>
>> Anyway, which opensource documentation tool do you recommend and why?
>> Please indicate in responses which you have experience with.
>
> Personally I use PHPDocumentor. One because of the support it has
> with
> the tags alone are normally far better than the others. The tags
> itself works with the svn/cvs tags as well ie (@version).
>
> The ease of using PHPDocumentor is insanely easy. Although it may
> take a little bit to actually get used to it and understand it as most
> documenting programs do, but if you are at all familiar with JavaDoc
> you will run right into it fine.
>
> To document future code is extremely easy, and even if you deprecate a
> function there are tags for that as well! Also tags to show that this
> function was available since a certain date.
>
> The quality and flexibility in my mind is amazing, there is only one
> thing more that I want is to be able to have inline code examples
> generated if more than one exists.

If you use latest version of the Zend Studio it also uses any
PHPDocumentor tags in your code to show help as you are coding, and
also to help with code completion. It's helped to make me a lot more
productive.

--
Chris Hope | www.electrictoolbox.com | www.linuxcdmall.com

Chris,
> If you use latest version of the Zend Studio it also uses any
> PHPDocumentor tags in your code to show help as you are coding, and
> also to help with code completion. It's helped to make me a lot more
> productive.
>

This is the same with PHPEdit

Mike

Mike Willbanks wrote:

> Chris,
>> If you use latest version of the Zend Studio it also uses any
>> PHPDocumentor tags in your code to show help as you are coding, and
>> also to help with code completion. It's helped to make me a lot more
>> productive.
>
> This is the same with PHPEdit

Good to know. Thanks.

--
Chris Hope | www.electrictoolbox.com | www.linuxcdmall.com

anthonymorris@yahoo.com wrote:
<snip>
> Anyway, which opensource documentation tool do you recommend and why?
> Please indicate in responses which you have experience with.

We use,
For PHP: PHPDocumentor <http://phpdoc.org>
For VB: VBDOX <http://vbdox.sourceforge.net/howto_java.html>
Others: Doxygen

All these tools can produce CHM documents. FWIW, doxygen has lot of
tags and options, but for PHP PHPDocumentor is the de facto.

--
<?php echo 'Just another PHP saint'; ?>
Email: rrjanbiah-at-Y!com Blog: http://rajeshanbiah.blogspot.com/