Re: [PHP-DEV] javadoc, phpdoc, XML, and PEAR From: chagenbu <email protected>
Date: 05/15/00

Quoting Joey <joey <email protected>>:

> A) There is already a system in PHP for inline docs
> B) This would not be compatible with XML versions of documentation

I really think that people are still speaking crosswise somewhat. We're not
talking about documenting c source - php modules. We're talking about
documenting php code - PEAR modules, and hopefully a wider standard. I'd hope
that this standard will be as simple as possible, because the main reason that
open source projects have poor documentation is that IT IS A PAIN IN THE ASS TO
WRITE! If you make every single person who wants to write a pear module learn
xml to document their code, you're going to get a lot less code contributed to
PEAR. The alternative is to have a team which will volunteer to document
everyone's modules, but that seems extremely limiting (in volume), and not a
good idea, since you want the person who wrote the code documenting it if
possible.

I like javadoc because it is: established with a large number of programmers,
simple, and still expressive enough to be more useful than a one-line summary. I
don't argue that XML is the way to go for comprehensive documentation - like the
php manual - but the package indexes that javadoc generates I find extremely
useful. We could even have phpdoc generate an XML skeleton for a package to aid
in writing comprehensive documentation along with the phpdoc summary. THAT would
be a great way to encourage people to write documentation, not make it too
complicated for them, and aid the process of getting more comprehensive docs,
all at the same time.

-chuck 

-- 
PHP Development Mailing List <http://www.php.net/>
To unsubscribe, e-mail: php-dev-unsubscribe <email protected>
For additional commands, e-mail: php-dev-help <email protected>
To contact the list administrators, e-mail: php-list-admin <email protected>