Cof... cof...
https://wiki.php.net/rfc/annotations
Good luck convincing php-src folks.
You'd be my hero.
On Mon, Jan 7, 2013 at 9:50 PM, Rasmus Schultz <ras...@mindplay.dk> wrote:
> On parsing annotations in docblocks: please don't.
>
> First of all, there are already plenty of established userland
> implementations - so there is really no need for this.
>
> Whatever you decide on in terms of syntax, most likely won't satisfy every
> the needs of every userland annotation library, so at least some of them
> most likely won't use it. You'd be creating more work for the maintainers
> of these frameworks, and they don't standard to gain anything from that
> work.
>
> In terms of performance, there is nothing significant to gain here - any
> good annotation engine/framework already caches parsed annotations.
>
> On the other hand, I would be interested in having support for actual
> annotation syntax (not docblocks) added to PHP. Real annotation syntax
> could have benefits over parsing docblocks, starting with the fact that
> most of what's currently in docblocks is documentation, and thus not very
> interesting at run-time for anything other than documentation generators.
> (again, documentation generators already have working parsers, and don't
> stand to gain anything significant from switching to a native docblock
> parser.) - also mind the fact that docblocks are a loose standard with many
> more variations since annotation libraries came around.
>
> The only real downside (in terms of run-time) to adding custom syntax, is
> that existing useful annotations (such as @var for property-types) would
> not be useful - but in another sense, that's a good thing, because (for the
> most part) in existing codebases, these were written as documentation, not
> intended for run-time consumption. IDEs and documentation tools can add
> support for new annotation syntax, and treat these consistently and code,
> which itself can be documented using phpdoc blocks.
>
> I would support and encourage a C# style syntax and behavior, e.g.:
>
> use my\lib\DataType;
>
> [DataType('datetime')]
> public $published_date;
>
> In other words, DataType is a class, implementing an interface for
> initialization - everything between the parentheses is interpreted
> basically the same way as in an array() statement, and is passed to the
> annotation instance after construction via an initialization method defined
> by the interface.
>
> I could elaborate tons more on this subject, as it's something I have spent
> a lot of time researching in different languages, prior to writing my own
> annotation library.
>
> It may strike you as odd that someone who implemented an annotation library
> based on docblocks is actually against annotations in docblocks - I mainly
> chose that option because it was the best option at the time. I'm not a C
> programmer, and I do believe that docblocks are the best approach for a
> native PHP implementation. For a native implementation, I'd prefer to see a
> clear separation between non-functional documentation metadata and
> functional annotation objects. While there is some overlap between the two,
> much of what is currently written as documentation (for example @var
> annotations) could be written as functional annotations when these have a
> meaningful purpose. After all, existing code with phpdoc-annotations most
> likely was not written with the intent of consuming that metadata at
> runtime, unless written for use with an annotation library.
>
> I would be happy to involve myself deeper in this, if others agree and
> would like to work on a new RFC.
>
> - Rasmus Schultz
>
--
Guilherme Blanco
MSN: guilhermebla...@hotmail.com
GTalk: guilhermeblanco
Toronto - ON/Canada
