On 11 May 2011 07:50, dukeofgaming <duke...@gmail.com> wrote:

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—they 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.