On 09.01.2013 02:38, Rasmus Schultz wrote:
A native implementation of PHP-DOC block parser for run-time purposes
(annotation libraries) is already available in the Reflection API,
There is no DocBlock parser in the Reflection API; you can merely
retrieve the T_DOC_COMMENT token.
and
already goes as deep as it needs to - going beyond simply finding and
extracting the docblocks would make little sense, as every annotation
library has it's own individual syntax, behaviors and features.
There are other types of project that benefit from the parsing of the
actual DocBlock without any support for Annotations. Examples follow
below.
There may
be a some libraries that could use a native implementation if it
happens to
fit their needs, but they most likely won't use it, because (A) they
won't
win anything by doing so, and (B) these libraries would become
incompatible
with anything other than bleeding-edge PHP.
I disagree with this,
A) Said applications and libraries win in the terms of performance and
standardization; this will offer a baseline for IDEs to offer proper
support for descriptions and tags and even more advanced features.
B) This issue arises with _any_ new feature that substitutes or
empowers
a userland functionality and I thus consider it a non-argument.
I am Lead Developer of phpDocumentor and I promise you, I'd use
this.
A native implementation of PHP-DOC parser for offline purposes
(documentation generators) is already available in userland, does the
job
fine, and does not rely on the Reflection API (as someone mentioned)
because loading every class in a large codebase is not feasible. If
you
provide a separate PHP-DOC parser, these projects most likely won't
use it,
because (A) see above and (B) see above.
Performance is key with documentation generators. Since DocBlocks are
the
most prevalent thing in a code base they could win with a core
implementation.
Also, as provided earlier, would standardization benefit the whole
community
that consumes DocBlocks and IDE vendors.
Who else would need to parse PHP-DOC blocks and why?
* WSDL Generators to extract descriptions and type information
* REST API documentation generators for the same reason
* HATEOAS libraries could benefit from the reading of the @uses tag
* Command Line Application frameworks could use the Command class'
description
for their help screen.
And more uses that I cannot think of within a few seconds.
--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php
