Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:64652
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: error (pb1.pair.com: domain mindplay.dk from 209.85.212.46 cause and error)
MIME-Version: 1.0
Date: Mon, 7 Jan 2013 21:50:15 -0500
Message-ID: <CADqTB_h4eh4mPi89uRps6vZWXjDEhUtcBopL7jmO-UgRuyf19w@mail.gmail.com>
To: internals@lists.php.net
Content-Type: multipart/alternative; boundary=bcaec5171e0163385904d2be01c4
Subject: Re: [PHP-DEV] [RFC] Reflection annotations reader
From: rasmus@mindplay.dk (Rasmus Schultz)

--bcaec5171e0163385904d2be01c4
Content-Type: text/plain; charset=ISO-8859-1

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

--bcaec5171e0163385904d2be01c4--