Hello,
Based on comments from the annotations thread, I have created a
docBlock parser RFC at http://wiki.php.net/rfc/docblockparser
This RFC does not deal with annotations per se, but only with the idea
of adding a function to the Reflection extension which would parse
docBlocks according to a set docBlock syntax into a simple associative
array containing three elements: short description, long description,
and an array of tags.
This is only meant to aid meta-data retrieval for classes and does not
automatically instantiate anything objects.
The RFC was meant to conform to existing convention on the formatting
of docBlocks - so one major way to improve it would be to note any
inconsistencies with accepted practice.
Feel free to improve in any other way as well, of course.
Thanks,
Chad
Am 16.09.2010 22:56, schrieb Chad Fulton:
Hello,
Based on comments from the annotations thread, I have created a
docBlock parser RFC at http://wiki.php.net/rfc/docblockparserThis RFC does not deal with annotations per se, but only with the idea
of adding a function to the Reflection extension which would parse
docBlocks according to a set docBlock syntax into a simple associative
array containing three elements: short description, long description,
and an array of tags.This is only meant to aid meta-data retrieval for classes and does not
automatically instantiate anything objects.The RFC was meant to conform to existing convention on the formatting
of docBlocks - so one major way to improve it would be to note any
inconsistencies with accepted practice.Feel free to improve in any other way as well, of course.
Thanks,
Chad
Hi Chad,
the RFC looks for me like a built-in PHPDocumentor parser. This can be
useful. The problem for me is that I cannot parse the file level doc
block. What is with tags like @Validator('blabla'). I cannot find an
example for this scenario.
Greetings,
Christian
Hello!
That is a good point, there would be no file-level doc block in the
RFC. Here is my reasoning for not including it in the RFC:
Since the motivation for this came from the desire for metadata for
PHP structures, it seemed inappropriate to include metadata at the
file level (since it's not a php structure).
As for the @Validator('blahbla'), I had thought it could be replicated with:
/**
- @Validator blahbla
*/
How to do multiple arguments would be up to user-land functions that
used the parsed doc comments, but one possibility is:
/**
- @Validator foo bar baz
*/
then when you wanted to retrieve these, you could do explode(' ',
$tags['Validator']); or similar.
However, more specific syntax could be added to allow "arguments" in
the doc block tags. I just feel like in this case absolute simplicity
is important.
Chad
On Thu, Sep 16, 2010 at 2:23 PM, Christian Kaps
christian.kaps@mohiva.com wrote:
Hi Chad,
the RFC looks for me like a built-in PHPDocumentor parser. This can be
useful. The problem for me is that I cannot parse the file level doc
block. What is with tags like @Validator('blabla'). I cannot find an
example for this scenario.Greetings,
Christian
hi,
That's nice a nice idea. The PHPDocumentator guys did something to
help the parsing via a pecl's extension
(http://pecl.php.net/docblock). Now, to implement the docbloc parsing
itself will require a parser usage (lemon or whatever else you want),
it will be freaking tricky, not necessary fast and very hard to be
interpreted by computers being. By the way, that's why annotations
exist and why annotations have new, smaller, easier to parse syntax.
Cheers,
Hello,
Based on comments from the annotations thread, I have created a
docBlock parser RFC at http://wiki.php.net/rfc/docblockparserThis RFC does not deal with annotations per se, but only with the idea
of adding a function to the Reflection extension which would parse
docBlocks according to a set docBlock syntax into a simple associative
array containing three elements: short description, long description,
and an array of tags.This is only meant to aid meta-data retrieval for classes and does not
automatically instantiate anything objects.The RFC was meant to conform to existing convention on the formatting
of docBlocks - so one major way to improve it would be to note any
inconsistencies with accepted practice.Feel free to improve in any other way as well, of course.
Thanks,
Chad--
--
Pierre
@pierrejoye | http://blog.thepimp.net | http://www.libgd.org
On Thu, 16 Sep 2010 21:56:04 +0100, Chad Fulton chadfulton@gmail.com
wrote:
Based on comments from the annotations thread, I have created a
docBlock parser RFC at http://wiki.php.net/rfc/docblockparserThis RFC does not deal with annotations per se, but only with the idea
of adding a function to the Reflection extension which would parse
docBlocks according to a set docBlock syntax into a simple associative
array containing three elements: short description, long description,
and an array of tags.This is only meant to aid meta-data retrieval for classes and does not
automatically instantiate anything objects.
Pointless.
Well, this will maybe speedup and standardize the usage of doc comments,
but it's very far from what we could do with real annotations.
By real annotations, I mean something the engine would recognize and that
we could use in the future to implement AOP functionality with annotations
or to implement other new features in the future, e.g.:
class A {
@ReadOnly
public $var;
@PropertyGetter("virtualPropertyName")
public function baz() { }
@ClassInvariant
public static function bar() { }
@InstanceInvariant
public function foo() { }
/**
* A closure that could be called as if it were a non-static method
* and which would be automatically rebound.
* @var Closure
*/
@MethodClosure("staticMethod" => false, "rebind" => true)
public static $clos;
@Before("self::whatever", instance=true) /* Or @After, or @Around */
@Log("entering foobar") /* user-defined specialization of Before */
@Precondition(...)
public function foobar() {}
}
The current implementation would not allow any of this, but at least it
opened way. A doc comment parser...
--
Gustavo Lopes
Hello,
Yes, this is not an RFC for annotations or to replicate the exact
functionality you wanted within doc comments.
However, there is support based on the annotations thread for "APIs to
parse doc blocks". I don't know what is meant by others (Zeev, Stas,
etc) when they say this. However, in writing this RFC I was nailing
down my interpretation of it. It may not be what they had in mind at
all, and that's fine by me.
I think that this approach has merit because of its simplicity. I
also think that the use cases mentioned in the Annotations RFC could
be equally served by this approach (PHPUnit, Doctrine, etc).
If you look at your own example above, the @ReadOnly, @PropertyGetter,
@ClassInvariant, and @InstanceInvariant are all trivially replicated
using the doc block approach. I strongly suspect the others would be
too, except that I'm not sure exactly what you meant by them.
I wrote this because it seems to me from comments in the annotations
thread that the main problem with the annotations RFC is that it mixes
something people want (simple metadata) with something people don't
want (new rules and a new syntax). It's definitely possible that I'm
wrong about this.
Either way, I think this would be a nice thing to have.
Thanks,
Chad
On Thu, 16 Sep 2010 21:56:04 +0100, Chad Fulton chadfulton@gmail.com
wrote:Based on comments from the annotations thread, I have created a
docBlock parser RFC at http://wiki.php.net/rfc/docblockparserThis RFC does not deal with annotations per se, but only with the idea
of adding a function to the Reflection extension which would parse
docBlocks according to a set docBlock syntax into a simple associative
array containing three elements: short description, long description,
and an array of tags.This is only meant to aid meta-data retrieval for classes and does not
automatically instantiate anything objects.Pointless.
Well, this will maybe speedup and standardize the usage of doc comments, but
it's very far from what we could do with real annotations.By real annotations, I mean something the engine would recognize and that we
could use in the future to implement AOP functionality with annotations or
to implement other new features in the future, e.g.:class A {
@ReadOnly
public $var;@PropertyGetter("virtualPropertyName")
public function baz() { }@ClassInvariant
public static function bar() { }@InstanceInvariant
public function foo() { }/**
* A closure that could be called as if it were a non-static method
* and which would be automatically rebound.
* @var Closure
*/
@MethodClosure("staticMethod" => false, "rebind" => true)
public static $clos;@Before("self::whatever", instance=true) /* Or @After, or @Around /
@Log("entering foobar") / user-defined specialization of Before */
@Precondition(...)
public function foobar() {}
}The current implementation would not allow any of this, but at least it
opened way. A doc comment parser...--
Gustavo Lopes
On Thu, 16 Sep 2010 21:56:04 +0100, Chad Fulton chadfulton@gmail.com
wrote:Based on comments from the annotations thread, I have created a
docBlock parser RFC at http://wiki.php.net/rfc/docblockparserThis RFC does not deal with annotations per se, but only with the idea
of adding a function to the Reflection extension which would parse
docBlocks according to a set docBlock syntax into a simple associative
array containing three elements: short description, long description,
and an array of tags.This is only meant to aid meta-data retrieval for classes and does not
automatically instantiate anything objects.Pointless.
Well, this will maybe speedup and standardize the usage of doc comments,
but it's very far from what we could do with real annotations.
I understand that you're coming from the point of view of annotations. However,
that does not make this proposal "pointless." There are many uses for it: it
would greatly speed-up and facilitate API documentation generators; it could be
used in a number of projects that scan docblock annotations in order to get
parameter and return value typehinting (we use this in ZF for the various server
classes), and more.
Let's argue this one on its own merits, and not on the basis of whether or not
it can be used for annotations parsing; that can and should be a separate, later
issue.
--
Matthew Weier O'Phinney
Project Lead | matthew@zend.com
Zend Framework | http://framework.zend.com/
PGP key: http://framework.zend.com/zf-matthew-pgp-key.asc
On Fri, 17 Sep 2010 13:41:33 +0100, Matthew Weier O'Phinney
weierophinney@php.net wrote:
Pointless.
Well, this will maybe speedup and standardize the usage of doc comments,
but it's very far from what we could do with real annotations.Let's argue this one on its own merits, and not on the basis of whether
or not it can be used for annotations parsing; that can and should be a
separate, later issue.
Fair enough, but it was not I who presented doc comments parsing as if it
were some sort of valid alternative for annotations, which is how the
topic came up...
--
Gustavo Lopes
Hello,
Based on comments from the annotations thread, I have created a
docBlock parser RFC at http://wiki.php.net/rfc/docblockparserThis RFC does not deal with annotations per se, but only with the idea
of adding a function to the Reflection extension which would parse
docBlocks according to a set docBlock syntax into a simple associative
array containing three elements: short description, long description,
and an array of tags.This is only meant to aid meta-data retrieval for classes and does not
automatically instantiate anything objects.The RFC was meant to conform to existing convention on the formatting
of docBlocks - so one major way to improve it would be to note any
inconsistencies with accepted practice.Feel free to improve in any other way as well, of course.
Thanks,
Chad--
+1 for this idea.
this can be a very useful tool/feature, and can extend the current
Reflection support without affecting anything else.
but as you and others said we don't have to choose between this feature and
the annotation support, because they server different purpose.
Tyrael
Hello,
Based on comments from the annotations thread, I have created a
docBlock parser RFC at http://wiki.php.net/rfc/docblockparserThis RFC does not deal with annotations per se, but only with the idea
of adding a function to the Reflection extension which would parse
docBlocks according to a set docBlock syntax into a simple associative
array containing three elements: short description, long description,
and an array of tags.This is only meant to aid meta-data retrieval for classes and does not
automatically instantiate anything objects.The RFC was meant to conform to existing convention on the formatting
of docBlocks - so one major way to improve it would be to note any
inconsistencies with accepted practice.Feel free to improve in any other way as well, of course.
Thanks,
Chad
Should my vote count: +1
This seems to be a solid enhancement to PHP as I believe it can be
useful in a multitude of situations.
I did miss 2 things while glancing the RFC:
- Inline tags, PHPDocs generally support tags inside the short and long
description (for example: {@see getTag()} ), see
http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_inlinetags.pkg.html - And a short description may be ended by a dot and newline (.) instead
of a white-line, see
http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#basics.docblock
Bonus would be to also add the docblock template operator but I find it
hard to determine the complexity of this, see
http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#basics.docblocktemplate
Kind regards,
Mike van Riel