On 11 May 2011 07:50, dukeofgaming <dukeofgam...@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. 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. -- Richard Quadling Twitter : EE : Zend @RQuadling : e-e.com/M_248814.html : bit.ly/9O8vFY -- PHP Internals - PHP Runtime Development Mailing List To unsubscribe, visit: http://www.php.net/unsub.php
