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

Quoting eschmid+sic <email protected>:

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

Okay. Correct me if I'm wrong, but isn't this system - and CODING_STANDARDS -
meant to apply to the php source code - ie, code written in c? If so, then
people writing code in php - like PEAR modules - aren't even expected to look at
CODING_STANDARDS...

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

Right! I think that a modification of javadoc is a good _inline_ system for
PEAR; it could probably even be used to generate a useful starting point for
external documentation, like I suggested before.

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

I (and I don't think Ulf) ever suggested changing the existing inline php docs.
We're just talking about inline documentation in PEAR modules - an entirely
different beast, as far as I'm concerned.

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

Yes - it's very useful. But a system like that takes a talented and dedicated
documentation team - correct me if I'm wrong, but I don't think you guys want to
take on maintaining documentation for every PEAR module, do you? So PEAR should
use a method of inline documentation that encourages individual authors to
document their work, in such a way that generates generally useful output.

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