On Wed, 15 Sep 2010 07:55:55 +0100, Zeev Suraski <z...@zend.com> wrote:
At 08:09 15/09/2010, Stas Malyshev wrote:
Phpdocs aren't "user documentation" only, not for a long time (I mean
the concept, not the particular application called phpDocumentor, of
course). They are being used as metadata in many places. You could
argue that's misguided but you can't ignore the fact that's what people
do. The "goals and usages" of those tags are exactly metadata - and
regardless of the annotations, I'd be happy if Reflection recognized it
finally (by integrating some kind of phpdoc tag parser).
I second that word for word. FWIW, I don't see it as misguided at all.
OK, here's why "doc comments" are insufficient:
1. You have to manually parse them (which is not easy; writing parsers is
quite error prone). You would also probably need to implement some form of
annotation inheritance.
2. There's no standardized way to express annotations, so the user will
have to learn a new syntax for each implementation.
3. Performance issues -- you to have to parse and validate the annotations
on each request, unless you implement your own caching mechanism. With
native annotations, you could use opcode caches to do parsing and
validation only on the first request.
4. Finally, and this is the most significant to me -- since PHP doesn't
know annotations (it only knows there's a blob a text), you cannot give to
certain annotations a meaning that would be recognized at an engine. With
annotations, we could, in the future, implement a special meaning for
@ReadOnly and @WriteOnly for properties and have stuff like:
@RunBefore("Log::writeMessage")
public LogAnnotation extends ReflectionAnnotation {
public $value;
}
...
@Log("Enterting method Foo::bar")
@RequiredRole("moderator")
public function bar() { }
without having to run the method through a framework that would recognize
those annotations in doc blocks. However, the only thing close to this in
the current implementation is @Inherited.
Finally, a separate issue is the syntactic one. Could we use the current
implementation but define the annotations in doc blocks instead?
If it comes to that, it'd be better than nothing. However, It would almost
certainly break BC (and subjectively, it feels wrong to mix annotations,
which have real impact on the application, with mere comments).
If the annotations were parsed only on request, it would not break BC in
the sense that whole old applications would stop working; however, when
upgrading PHP and the framework to a new version that would support
annotations, it could misinterpret old doc comments that look like
annotations (or most likely, malformed annotations). More importantly, it
would break a compelling reason to have annotations (point 4.).
--
Gustavo Lopes
--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php
