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

Stig: Thanks for the reply! :)

>There is really no "conflict" between the current way in PHP of marking
>up prototypes, and XML documentation. From the inlined function
>prototype you can generate a RefNameDiv element in the XML, and in the
>following one-liner you have the contents of the RefPurpose element.
>

        I was aware of this. I am just dreaming, here, and I figured
        someone would bring me back down to earth...

>I don't mean to be Mr. Party-pooper, but having entire PEAR files
>conform to a DTD means that PHP has to be an XML parser, which would
>slow down the parsing considerably. Any feature slowing down parsing
>needs to justify its existence, and I don't think making inline
>documentation in a certain way justifies it.

        I agree whole-heartedly. I hadn't really thought it all the
        way through...

>
>The idea you toss in about looking for deprecated functions is cool.
>The functionality you are suggesting (not only checking for specific
>functions, but tracing the output as well) is called static code
>analysis. I'm not a compiler guru, but I have a feeling writing one is
>about the same amount of work as writing an optimizing parser/compiler.
>:-)
>

        Hmm...I was simply thinking of something along the lines of
        "tidy". I, also, am not a compiler guru, but I note that it only
        takes 24 files for tidy, and this warns of things like using
        the font tag, which is a deprecated HTML tag.

        There are a lot of tools in XML that look to me like they should
        make something like this simpler...just write a DTD, and validate
        against it. That is kind of a simplistic outlook, I know, but it's
        about as much XML as I have dealt with so far (mostly, just read
        some of the PH/PTR books).

>Catching unquoted strings and so on could be done in a "PHP lint"
>program. It would make sense to extend the parser (Zend) with a mode
>for this.
>
>Take a look at the file "dblib.dsl" in the DSSSL stylesheets we use for
>the PHP Manual, it has comments with some sort of markup before
>functions, and a tool called "dsl2man" apparently converts this to
>DocBook format..
>

        Maybe inline is not the right place for what I am thinking of.
        Maybe what I am thinking of has no place whatsoever in PHP/PEAR,
        but before it gets completely shot down, let me try to pass the
        vision along...

        I see aweb interface to PEAR. Since I agree that maybe inline is
        not the right way for this to work, let's say the user is asked to
        to upload a normal PEAR file, perhaps using current
        CODING_STANDARDS, or whatever comes out of all of this...

        The "thingy" (as Larry Wall would say) that handles the file
        upload runs the PEAR file through my theoretical XML validating
        parser, and generates a companion XML file that can be used as the
        "online documentation" for this particular PEAR module. When it
        has finished (before it even starts?) building the XML document,
        it simply attempts to validate it.

        If the document can be validated (is both well-formed and conforms
        to it's DTD), then the PEAR file is added to the PEAR dir, and the
        XML file is added to the list of to-be-updated-on-some-website-
        somewhere files.
        

>Since this involves all of PHP, not only PEAR, php-dev is probably the
>right place for this discussion.

        I didn't really talk about the original question(s), which were
regarding your use of javadoc inside of PEAR, and whether there was any
interest in a similar language for inline docs, phpdoc, which is titled
more towards PHP in specific. PHP itsself /HAS/ a documentation system,
and it works well. If PEAR were to follow in its footsteps, this would be
a good thing, also. But while we have a chance, maybe we should also look
at some of the ideas that others have, and see what can be stolen from...I
mean, gleaned from...them. ;)

        --Joey Smith

Please forgive the long sig:

*** Notice To Bulk Emailers: Attention! Pursuant to US Code, Title 47,
Chapter 5, Subchapter II, 227, any & all unsolicited commercial e-mail
sent to this address is subject to a download and archival fee in the
amount of the $1500 US and copies will be forwarded to domain
administrators. Emailing denotes acceptance of said terms! 

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