Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:64716
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)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8;
 format=flowed
Content-Transfer-Encoding: 7bit
Date: Wed, 09 Jan 2013 07:01:56 +0100
To: Rasmus Schultz <rasmus@mindplay.dk>
Cc: Stas Malyshev <smalyshev@sugarcrm.com>, <internals@lists.php.net>
In-Reply-To: <CADqTB_gMcDU69N=SNR-uCOmmbvXfEJ8dFYxpvZmgbK7XTXUsUA@mail.gmail.com>
References: <CADqTB_h4eh4mPi89uRps6vZWXjDEhUtcBopL7jmO-UgRuyf19w@mail.gmail.com>
 <50EBDEEE.8070605@sugarcrm.com>
 <CADqTB_gMcDU69N=SNR-uCOmmbvXfEJ8dFYxpvZmgbK7XTXUsUA@mail.gmail.com>
Message-ID: <55cfd01c70ea2798a700a083a6c36935@naenius.com>
User-Agent: Web-Oke Webmail/0.7.1
Subject: Re: [PHP-DEV] [RFC] Reflection annotations reader
From: mike.vanriel@naenius.com (Mike van Riel)

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.