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

> 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.

        Actually, the real problem is that I am not very good at
        communcation. :)
        I really think that the current system of inline documentation
        as it is being used in php source is as easy to learn as javadoc,
        and don't see any reason why people just don't use it for PEAR as
        well. The XML idea is, as I said, something my friend and I are
        throwing around...read my response to Stig about inlining XML.

>
> 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.

        Yes, this is the core of the idea I was trying to get across, I
        just did not express it well. Again, see my reply to Stig from
        late last night.

>
> -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>
>
> 

-- 
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>