docBlock Parser RFC

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/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

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/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

--

--
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/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.

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,

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

--

+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/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

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