Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:49619
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: <internals@lists.php.net>
MIME-Version: 1.0
Date: Mon, 13 Sep 2010 17:38:37 +0200
In-Reply-To: <7.0.1.0.2.20100913145703.0d226d90@zend.com>
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>
Message-ID: <0f5a11f744bbcf99d8217f40da3a302a@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: PHP Annotations RFC + Patch
From: kontakt@beberlei.de (Benjamin Eberlei)


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