Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:49663
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: error (pb1.pair.com: domain beberlei.de from 87.230.78.165 cause and error)
To: Zeev Suraski <zeev@zend.com>
MIME-Version: 1.0
Date: Wed, 15 Sep 2010 10:45:37 +0200
Cc: Stas Malyshev <smalyshev@sugarcrm.com>, Pierre Joye <pierre.php@gmail.com>, 
 Pierrick Charron <pierrick@webstart.fr>, 
 Jonathan Bond-Caron <jbondc@openmv.com>, Nate Abele <nate.abele@gmail.com>, 
 PHP Development <internals@lists.php.net>
In-Reply-To: <7.0.1.0.2.20100915085504.17eab4d8@zend.com>
References: <39505F13-655A-43AF-941E-77750B7F7201@gmail.com> <001601cb543a$d81ebac0$885c3040$@com> <AANLkTikxw_xHn2fosykSwTat_qsGA16KriFinqc8Btrq@mail.gmail.com> <4C8FC695.2060800@sugarcrm.com> <AANLkTimOaicMidzH8oYWcieaCyx2bLefPGkXGQDZPQ6Y@mail.gmail.com> <4C8FD72B.1070108@sugarcrm.com> <AANLkTimEMdn6Z64O0Jt9KYEdHfDRa0iLt5eh1D16i_st@mail.gmail.com> <4C906333.4030204@sugarcrm.com> <7.0.1.0.2.20100915085504.17eab4d8@zend.com>
Message-ID: <12617cf66ae07d7a2fd79a293ed69b85@beberlei.de>
User-Agent: RoundCube Webmail/0.3.1
Content-Transfer-Encoding: 8bit
Content-Type: text/plain; charset=UTF-8
Subject: Re: [PHP-DEV] Re: Re: PHP Annotations RFC + Patch
From: kontakt@beberlei.de (Benjamin Eberlei)


Hi Zeev and Stas,

I wouldnt mind extending doc block metadata support instead of adding a
new syntax.

I agree with you that PHP Docs allow metadata and they can be used for
that (and some people do, including me), however what the annotation patch
+ rfc tries to achieve is something going beyong $refl->getDocComment()
returning a string only. The string only return leads to hunderets of
different approaches for annotating metadata in all the different
frameworks and libraries. A single unified syntax would be benefitial.

That is why I don't know if it will even be possible to extend the doc
blocks in a generic way that does not break half the applications out
there.

When extending doc-blocks there is probably new method required
$refl->getParsedDocComment() which then returns an array of metadata for
that particular refl instance. Now here the syntax would be a problem, can
we find something that does not break for all the different usages of
docblocks out there? Since the method/parsing would be nested, on request
only it wouldnt break any application that does not use parsed doc
comments. However for applications that do, a syntax needs to be found
that:

1. does not break for various type hinting doc syntaxes
2. does not break for various commenting styles

Can someone come up with additional pitfalls?

greetings,
Benjamin

On Wed, 15 Sep 2010 08:55:55 +0200, Zeev Suraski <zeev@zend.com> wrote:

    At 08:09 15/09/2010, Stas Malyshev wrote:

        Phpdocs aren't "user documentation" only, not for a long time (I
mean the concept, not the particular application called phpDocumentor, of
course). They are being used as metadata in many places. You could argue
that's misguided but you can't ignore the fact that's what people do. The
"goals and usages" of those tags are exactly metadata - and regardless of
the annotations, I'd be happy if Reflection recognized it finally (by
integrating some kind of phpdoc tag parser). 

    I second that word for word. FWIW, I don't see it as misguided at all.
Zeev