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

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

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

Ok.

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

I understand this also.

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

We need only one talented and dedicated documentation person to fold even
the PEAR documentation into another documentation. Maybe into the manual
itself. Hartmut can even fold a javadoc documentation in the main manual.
Believe me.

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