Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:49745
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain naenius.com designates 83.96.159.14 as permitted sender)
To: Chad Fulton <chadfulton@gmail.com>
Cc: internals@lists.php.net
In-Reply-To: <AANLkTinGFY8OobnjxEm6EDZyrqrTtvMJdceFMgAcGb7t@mail.gmail.com>
References: <AANLkTinGFY8OobnjxEm6EDZyrqrTtvMJdceFMgAcGb7t@mail.gmail.com>
Content-Type: text/plain; charset="UTF-8"
Date: Fri, 17 Sep 2010 10:38:30 +0200
Message-ID: <1284712710.4755.49.camel@mvriel-unet>
Mime-Version: 1.0
Content-Transfer-Encoding: 7bit
X-Antivirus-Web-Oke.nl: Seems clean.  You should still use an Antivirus Scanner
Subject: Re: [PHP-DEV] docBlock Parser RFC
From: mike.vanriel@naenius.com (Mike van Riel)

On Thu, 2010-09-16 at 13:56 -0700, Chad Fulton wrote:
> 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