On 2011-05-10, "guilhermebla...@gmail.com" <guilhermebla...@gmail.com> wrote:
> There's just one reason that it cannot be possible to do inside docblocks:
> - Code with and without comments should act the same.
Why?
Would you expect phpDocumentor to work without docblocks? No.
Would you expect to know parameter types and return values without
docblock annotations? No.
In each of these cases, we know the capabilities based on the _comment_ -
and we know that stripping out the comment and running specific tools on
the code will simply not work. I'd expect the same of annotations via
docblocks.
There are no good reasons to strip out docblock comments at this point
in PHP's history -- you don't gain speed, you don't improve parsing
time; about the only reason I can see to do so would be to minimize file
size for deployment -- and I'd argue even that is hard to justify.
So, in sum, if your code depends on annotations support, you know that
you cannot strip the comments. That's an easy rule to follow, and
doesn't require a new PHP syntax.
> Also, no matter if it's inside docblocks or not, we'd still have a new
> syntax. No matter what you do. Even a key => value is a new syntax.
> But it seems that none notice what I've been trying to express with
> the patch: key => value is not enough.
> Doctrine and Symfony are 2 projects that requires more than key/value
> support, because annotations declaration requires state, something not
> possible with k/v.
This is very easy to support in userland. I'd argue that a
ReflectionDocComment class with the following signature would be
sufficient:
getShortDescription()
getLongDescription()
getAnnotations()
hasAnnotation($name)
getAnnotation($name)
setAnnotationParser($callback)
Annotations would be simply key/value pairs, and by default annotations
would be recognized using the already popular standard of
@annotationName, with the value being everything up to the next
annotation or the end of the docblock.
It would be up to the given annotation _CONSUMER_ to determine how to
consume the value. With facilities such as json_decode(), you can
already even mimic native PHP structures to a large degree.
For cases where you want to utilize a different annotation format, the
ability to set an alternative parser would allow you to write such a
facility as an extension or in userland code, and its return value would
be used to seed the annotations accessors.
> Anyway, someone asked me previously if other languages support
> "complex" annotations like I suggest, my answer is YES and I even
> included in RFC the links to .NET and Java implementation examples.
I'm not one of those people. I already know that the support exists
elsewhere. I'm simply not convinced we need anything outside of the
ability to grab annotations from docblocks -- something that can be done
in userland now, but which could be sped up with native extensions.
> On Tue, May 10, 2011 at 12:57 PM, Matthew Weier O'Phinney
> <weierophin...@php.net> wrote:
> > On 2011-05-10, Drak <d...@zikula.org> wrote:
> > > --0016e6db295ac0d29504a2e4229c
> > > Content-Type: text/plain; charset=UTF-8
> > >
> > > On 10 May 2011 09:27, Mike Willbanks <pen...@gmail.com> wrote:
> > >
> > > > I would argue that the introduction of this into the core is adding
> > > > more feature bloat into the language that is not quite needed at
> > > > this point.
> > >
> > > Annotations cannot be considered bloat because are being used
> > > increasingly everywhere that is a clear indication that they are
> > > required as part of the PHP core as much as many of the Spl classes.
> > > It should be clear by now that the PHP community really do want
> > > annotations.
> >
> > Can you back this up, please?
> >
> > Just because developers are using annotations does not necessarily mean
> > we need a new syntax.
> >
> > > At this stage, if someone has done the work to make this
> > > happen, the discussion really should be more about polishing that
> > > contribution and making sure it provides a robust solution to this
> > > feature than trying to postpone or find reasons to put this off.
> >
> > I've gone on record as stating that annotations within docblocks are
> > sufficient, and would rather see native support for parsing docblocks
> > for annotations than introducing a new syntax. Others have stated the
> > same. I'd like to see why a new syntax is considered "necessary", and
> > why native support for docblock annotations is not considered a
> > reasonable path.
--
Matthew Weier O'Phinney
Project Lead | matt...@zend.com
Zend Framework | http://framework.zend.com/
PGP key: http://framework.zend.com/zf-matthew-pgp-key.asc
--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php
