Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:49637
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain sugarcrm.com designates 67.192.241.133 as permitted sender)
Message-ID: <4C8E6E74.3060207@sugarcrm.com>
Date: Mon, 13 Sep 2010 11:33:24 -0700
Organization: SugarCRM
User-Agent: Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10.6; en-US; rv:1.9.2.9) Gecko/20100825 Thunderbird/3.1.3
MIME-Version: 1.0
To: Benjamin Eberlei <kontakt@beberlei.de>
CC: "internals@lists.php.net" <internals@lists.php.net>
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>
In-Reply-To: <0f5a11f744bbcf99d8217f40da3a302a@beberlei.de>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit
Subject: Re: [PHP-DEV] Re: PHP Annotations RFC + Patch
From: smalyshev@sugarcrm.com (Stas Malyshev)

Hi!

> 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.

Nothing prevents us from using phpdocs for non-human-reading purposes. 
Actually, there is quite a lot of code that already does it 
successfully. I don't see anything heretical in having phpdoc tag parser 
in reflection and using it for metadata purposes - after all, phpdoc 
currently IS being used as metadata and actually it was its intent from 
the start.

> Primary difference of Annotations, they are not only human- but also
> enforced to be machine-readable. Annotations are runtime configuration or

phpdoc tags are enforced to be machine readable as well.

> metadata, throwing compile time parse errors when not followed correctly.

There's no such thing as compile time in PHP. Practically everything in 
PHP is runtime. And as I see, people want validation logic in their 
annotations - which makes it even more runtime.

> 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.

What prevents you from using plain old way of adding information to 
classes? I understand that new syntax is much cooler than boring old one 
- but besides that?

> 1. Developers should expect to be able to delete a comment/docblock
> without altering the code-path.

It's circular argument. If phpdoc is used for metadata, they can't.

> 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.

How it's a bad thing? IDEs can do whatever they want, and PHP parser 
shouldn't be broken by metadata.

> 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.

If you miss single dollar, comma or = sign, there could be errors too. So?

> 4. every IDE or code-highlighting prints them in light grey, making them
> sort of invisible.

Fix your IDE. My IDE knows about what phpdoc tags are :) Some IDEs 
lagging behind is not an argument in language design. IDEs can be fixed.
-- 
Stanislav Malyshev, Software Architect
SugarCRM: http://www.sugarcrm.com/
(408)454-6900 ext. 227