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

On Mon, May 15, 2000 at 03:32:19PM -0400, chagenbu <email protected> wrote:
> 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.

The current system to write folding hooks into the PHP source is very
simple. But almost all coders haven't seen the result of this effort and
can or will not follow the CODING_STANDARDS.

Hartmut Holzgraefe was able to build a database with all function entries
(around 1600) and list them in a alphabetical order. This list lists all
occurencies in which version each functions appears and in which language
it is already documented.

I don't see any need that PEAR modules must have the same inline docs like
the PHP source code. Useful information could be extracted from every sort
of inline docs.
 
> 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.

The same here. But don't touch the existing inline docs. In PHP 4 there
should be more. For the comprehensive docs, this mean, we can place that
information directly into the manual so users can make an annotation if
there is something missing.

Look at Hartmuts work at http://www.zugeschaut-und-mitgebaut.de/php/ and
you should know what I mean. A manually sorted list of the folding hooks
(or protos) can be found in Rasmus Pocket Reference.

-Egon 

--
Grueninger Str. 6, 70599 Stuttgart
http://php.net/manual/, http://php.net/books.php3
http://www.uni-hohenheim.de/~windband  
http://snaps.php.net/manual/, http://www.zend.com/

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