Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:52291
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: error (pb1.pair.com: domain mohiva.com from 178.63.228.54 cause and error)
Message-ID: <4DCA7F74.5060306@mohiva.com>
Date: Wed, 11 May 2011 14:22:12 +0200
User-Agent: Mozilla/5.0 (X11; U; Linux x86_64; en-US; rv:1.9.2.17) Gecko/20110430 Lightning/1.0b3pre Thunderbird/3.1.10
MIME-Version: 1.0
To: internals@lists.php.net
References: <4DC729EE.9090600@sugarcrm.com> <4DC75FFF.40008@lerdorf.com> <4DC7A7F0.4000504@sugarcrm.com> <BANLkTinn3+MCrSd7BAJCU03FMkuRAeydvA@mail.gmail.com> <4DC819D0.5010008@lerdorf.com> <BANLkTi=K8vc3wvwkKVtLS9o0Oh0itB_dTg@mail.gmail.com> <4DC81ED6.1050902@sugarcrm.com> <BANLkTikhJ1Z0Gk-cSivoFBFs1Fx8CHz=mA@mail.gmail.com> <8757232E56758B42B2EE4F9D2CA019C9013F9F59@US-EX2.zend.net> <BANLkTi=0OFHjfSyv3w+3f5+gcPVV7beoeA@mail.gmail.com> <4DCA2192.4080201@lsces.co.uk> <BANLkTimpauJ3Dq4LSW+3DKXd6zznHj_-iQ@mail.gmail.com> <BANLkTim0UQC0DCnnQMG3eyn0QPab5z7Ypw@mail.gmail.com>
In-Reply-To: <BANLkTim0UQC0DCnnQMG3eyn0QPab5z7Ypw@mail.gmail.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Subject: Re: [PHP-DEV] annotations again
From: christian.kaps@mohiva.com (Christian Kaps)

Am 11.05.2011 13:31, schrieb Richard Quadling:
> On 11 May 2011 07:50, dukeofgaming <dukeofgaming@gmail.com> wrote:
>> It is really troubling to read that statement. Seems there are still some
>> that don't really have a clue of what annotations are, even when the RFC
>> clearly links to them. Annotations ARE NOT documentation; in the case of
>> PHP, documentation is being used as annotations because there is no language
>> implementation, which exists in other languages (Java, .NET) and they are
>> widely used. Also, some use annotations as documentation (e.g. store the
>> class version), but again, annotations ARE NOT documentation. Don't let the
>> "@" notation shared with docblock fool you.
>>
>> Guilherme, I think its easy to assume that people already have some sense of
>> what annotations are, but perhaps the wiki entry could be more educational
>> about it?. The first time I read about annotations it was from this link:
>> http://download.oracle.com/javase/tutorial/java/javaOO/annotations.html;
>> perhaps an intro like that could help to make the case for annotations
>> crystal clear?.
> 
> I'm guessing experience and interpretation is everything here.
> 
> From reading the Oracle page, to me, it seems annotations ARE
> documentation. It just depends upon who or what is reading them.
> 
> The first line of the page ...
> 
> "They have no direct effect on the operation of the code they annotate".
> 
> In other words, annotations are just like comments. At least in terms
> of what I understand the "compiler" does and what the "runtime
> processing" does.
> 

They have no direct affect of the operation of the code they annotate,
but they have affect of the code which runs the annotated code. So
annotations are no comments.

> 
> The use of the @ isn't a fooling (according to Oracle) ... "The use of
> the "@" symbol in both Javadoc comments and in annotations is not
> coincidental—they are related conceptually.".
> 

I think the usage of the @ is historical. Because Java annotations in
the first implementation were DocBlock annotations parsed by XDocklet.
Starting with version 5 of the Java specification, they implemented
Annotations as part of the language.

http://www.devx.com/Java/Article/27235

> 
> What I can't see from the link is _WHY_ annotations can't just be
> docblocks? Annotations and comments don't affect the code. Annotations
> and comments would need to be parsed to read them.
> 
> I understand that caching of the annotation could be an issue. And
> this leads to a gap in my knowledge/understanding. Why does _this_
> script need to know anything about its annotations? Especially as
> "They have no direct effect on the operation of the code they
> annotate". It would seem wasteful to process dead data for no purpose
> in _this_ script. It only seems useful for some sort of external
> process reading the annotation/comment (say a documentor or a tool to
> build code for runtime operation). In those cases, these are one offs
> (ish), so caching would not seem to serve any real benefit here.
> 
> 
> Whilst I think the syntax of the annotation may be worth discussing,
> the annotation can surely only exist in a comment, at least with
> regard to PHP.
> 
> 
> And I'm guessing that the primary use of annotations within PHP would
> be in runtime processing, so is this really about the parsing of
> docblocks.
> 
> I think using PHP code in a docblock (with the appropriate tag ...
> @annotation maybe) would cover the requirements. Possibly. Due to
> phpdocumentor not being updated to handle namespaces yet, annotations
> are also not going to work correctly there.
> 
> 
> Richard.
> 
> 
> 
> 

Why not learning from Java and implement annotations in the way
Guilherme proposed it? I think they had good reasons for the new
implementation. Maybe someone has a link which points to such discussion.

Best regards,
Christian