Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:52290
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain gmail.com designates 209.85.216.42 as permitted sender)
DomainKey-Status: bad
DomainKey-Signature: a=rsa-sha1; c=nofws;
        d=gmail.com; s=gamma;
        h=mime-version:reply-to:in-reply-to:references:from:date:message-id
         :subject:to:cc:content-type:content-transfer-encoding;
        b=ao2yCFEPIPmjMdnlVOKuuH4PKO6O2Y4PfmPgxN/vFUmgx3fTNRpeuEjzR0UyfzvWsZ
         cC1qPuX10mz3m9pH5SKCb65l/KKtkJ2bQhyvsaWUc6OEZXLSPjSiPaYgtyhyZnQcfx8V
         GvLOCldy/RPhFdzYQk9OV9siPi7jseLFyp8Zs=
MIME-Version: 1.0
Reply-To: RQuadling@GMail.com
In-Reply-To: <BANLkTimpauJ3Dq4LSW+3DKXd6zznHj_-iQ@mail.gmail.com>
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>
Date: Wed, 11 May 2011 12:31:28 +0100
Message-ID: <BANLkTim0UQC0DCnnQMG3eyn0QPab5z7Ypw@mail.gmail.com>
To: dukeofgaming <dukeofgaming@gmail.com>
Cc: Lester Caine <lester@lsces.co.uk>, PHP internals <internals@lists.php.net>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable
Subject: Re: [PHP-DEV] annotations again
From: rquadling@gmail.com (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 langu=
age
> 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 t=
he
> "@" 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 educationa=
l
> 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.


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=E2=80=94they are related conceptually.".


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.




--=20
Richard Quadling
Twitter : EE : Zend
@RQuadling : e-e.com/M_248814.html : bit.ly/9O8vFY