Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:49622
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain mohiva.com designates 78.46.69.5 as permitted sender)
MIME-Version: 1.0
Content-Type: text/plain;
 charset=UTF-8
Content-Transfer-Encoding: 7bit
Date: Mon, 13 Sep 2010 17:48:35 +0200
To: Benjamin Eberlei <kontakt@beberlei.de>
Cc: internals@lists.php.net
In-Reply-To: <0f5a11f744bbcf99d8217f40da3a302a@beberlei.de>
References: <AANLkTimuWDV=9AA63_9M6cQSp9riCPE214sUNdoV3tQn@mail.gmail.com>
 <4C873C0F.1010200@zend.com>
 <AANLkTimdCnW3ABq5QSnBa78H14e2LPBa=Kt2txU0sTD4@mail.gmail.com>
 <4C879613.7090709@zend.com>
 <AANLkTim-dHYyJxX2R3-PBVqqa3sv3+zKYr7zw7QvyngJ@mail.gmail.com>
 <4C887D2B.2000605@zend.com> <4C8AC526.7000505@sugarcrm.com>
 <AANLkTikpCGj2zVNQmC1gUWaRSpsQD=qNrETi90wj_No7@mail.gmail.com>
 <4C8B6168.30504@mohiva.com>
 <AANLkTinuD_Aga-CbsbSq-23MTyOLPGrBEswTm=JtBY0H@mail.gmail.com>
 <4C8BC81E.8000605@sugarcrm.com>
 <AANLkTinFSqCFUE3P5XvjJPwUGZqYrQR_9VHAXAWSL=rv@mail.gmail.com>
 <7.0.1.0.2.20100913145703.0d226d90@zend.com>
 <0f5a11f744bbcf99d8217f40da3a302a@beberlei.de>
Message-ID: <eff060551785b7c79370be6099a840dc@localhost>
User-Agent: RoundCube Webmail/0.4
Subject: Re: [PHP-DEV] Re: PHP Annotations RFC + Patch
From: christian.kaps@mohiva.com (Christian Kaps)

Hi Benjamin,

I agree with you 100 percent.

Greetings,
Christian

On Mon, 13 Sep 2010 17:38:37 +0200, Benjamin Eberlei
<kontakt@beberlei.de> wrote:
> I strongly disagree!
> 
> PHPDocs are for what their name suggests, for comments, not for runtime
> code information. They allow arbitrary characters, their intent is for
> human-readible documentation only.
> 
> Yet they are used for service description (Zend_Soap_Autodiscover,
> Zend_XmlRpc), metadata mapping or phpunits "annotations", just because
> there is nothing better suited.
> 
> Primary difference of Annotations, they are not only human- but also
> enforced to be machine-readable. Annotations are runtime configuration or
> metadata, throwing compile time parse errors when not followed correctly.
> That has nothing to do with documentation, it is an very elegant way to
> extend classes, methods and properties with metadata information,
> configuration and code right next to each other.
> 
> The primary target for annotations are framework and library integrations:
> validation, forms, metadata mapping, static mvc configuration such as
> routing, view selection or acls. Why do these features not exist with
> current php libraries yet? Because developers see php doc blocks for what
> they are: Comments!
> 
> With Doctrine2 and Symfony2 we see some early experiments with annotations
> in PHP Docs, but they only highlight the drawbacks:
> 
> 1. Developers should expect to be able to delete a comment/docblock
> without altering the code-path.
> 2. Errors in the Doc-Blocks "expected formatting" are left for the
> userland developer to detect. IDEs or the PHP Parser simply don't care.
> 3. There is no real difference for a human only readable doclbock starting
> with /** or /*, however PHP just doesnt publish the /* docblocks to the
> userland, leading to countless errors when that single star is missing.
> 4. every IDE or code-highlighting prints them in light grey, making them
> sort of invisible.
> 
> That is why annotations are needed, they make metadata a language level
> construct, not a hack that is possible, because Reflection allows us to
> access the comments of methods, functions, classes, ...
> 
> greetings,
> Benjamin
> 
> On Mon, 13 Sep 2010 15:05:57 +0200, Zeev Suraski <zeev@zend.com> wrote:
>> At 20:24 11/09/2010, Pierre Joye wrote:
>>>On Sat, Sep 11, 2010 at 8:19 PM, Stas Malyshev <smalyshev@sugarcrm.com>
>>>wrote:
>>> > Hi!
>>> >
>>> >> The separator never was a problem... but I definately don't want to
>>> >> see another 6 months just to define what would the separator be.
>>> >> If we need to drop [] in favor of array support, I vote for ! as
>>> >> separator.
>>> >
>>> > The separator is not a problem (even though 1-char one produces much
>>> > less
>>> > clutter). The cryptic syntax is.
>>>
>>>It seems that there is a misunderstanding about the goals of the
>>>annotations. They are not meant to be read by human being
>>>(javadoc/phpdoc/etc. are) but to be parsed automatically to be used
>>>for services.
>>>
>>>In that sense, to have a syntax closed to one of the best (or less
>>>worst, if you are on the opposed side ;-) syntax out there (c#/.net)
>>>may be a good thing to do, instead of re einventing the php wheel.
>>
>> I'm not sure we've seen a good reason to add annotations instead of
>> using PHPDoc.  Sure, PHPDoc isn't a perfect fit for certain purposes,
>> but I think it certainly falls in the good-enough fit for most
>> purposes.  It's also both machine and human readable, and best of all
>> - it's already there.
>> There should be overwhelmingly strong reasons to add a whole new
>> branch of syntax to PHP, I for one don't see the huge gain
>> annotations bring on top of PHPDoc.
>>
>> Zeev