Re: annotations again

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