Native Annotation Syntax

9 years ago by Pedro Cordeiro — view source

unread

Hello.

I'd been reading some old RFCs recently, and I found two RFCs on the
subject of annotations, both by Guilherme Blanco. The first one, which
proposed a native syntax for annotations, is marked as 'declined', and I
couldn't find a discussion for it anywhere. The second one, which proposes
retrieving annotation from DocBlocks through reflection is 'inactive', with
no further explanation.

I'd really like to see native annotation support for PHP that doesn't live
in comments.

Is there a reason those RFCs were dropped, or was it just lack of interest?

Pedro.

9 years ago by Benjamin Eberlei — view source

unread

On Tue, Nov 24, 2015 at 5:30 PM, Pedro Cordeiro pedronaroga@gmail.com
wrote:

Hello.

I'd been reading some old RFCs recently, and I found two RFCs on the
subject of annotations, both by Guilherme Blanco. The first one, which
proposed a native syntax for annotations, is marked as 'declined', and I
couldn't find a discussion for it anywhere. The second one, which proposes
retrieving annotation from DocBlocks through reflection is 'inactive', with
no further explanation.

I'd really like to see native annotation support for PHP that doesn't live
in comments.

Is there a reason those RFCs were dropped, or was it just lack of interest?

There was a vote on the declined one from Guilherme, which was in the old
mailing list style,
you'd have to search the mailing ilst archives to find the thread with the
discussion and voting.

Pedro.

9 years ago by Rowan Collins — view source

unread

I'd been reading some old RFCs recently, and I found two RFCs on the
subject of annotations, both by Guilherme Blanco. The first one, which
proposed a native syntax for annotations, is marked as 'declined', and I
couldn't find a discussion for it anywhere. The second one, which proposes
retrieving annotation from DocBlocks through reflection is 'inactive', with
no further explanation.

I'd really like to see native annotation support for PHP that doesn't live
in comments.

Is there a reason those RFCs were dropped, or was it just lack of interest?

I think one of the stumbling blocks in recent discussions of annotation
support is just how much support should be provided; off the top of my
head, this could be:

a few extra functions in reflection classes to parse the items within
a docblock (docblocks are already handled in reflection separately from
normal comments)
automatic instantiation of a set of standard Annotation objects with
the text content above
automatic instantiation of classes based on the annotations provided
built-in support for applying annotations to the objects they appear
on, perhaps in the form of full Aspect-Oriented Programming support

At first sight, these seem like details which could be tweaked later,
but they make a difference to what syntax to standardise: is the
annotation name just a string, or a valid class name? is the value of
the annotation just a string, or a parseable PHP expression? is it more
useful to use the de facto existing syntax in DocBlocks, or to add a new
keyword or operator? etc

The devil, as ever, is in the detail.

Regards,

--
Rowan Collins
[IMSoP]

9 years ago by Sara Golemon — view source

unread

At first sight, these seem like details which could be tweaked later, but
they make a difference to what syntax to standardise: is the annotation name
just a string, or a valid class name? is the value of the annotation just a
string, or a parseable PHP expression? is it more useful to use the de facto
existing syntax in DocBlocks, or to add a new keyword or operator? etc

If we're going to use something in the docblock, then I wouldn't want
it parsed on compilation, but rather have it be an on-demand parse
while reflecting. The reason being that there are plenty of
docblock'd PHP libraries out there using invalid annotations because
they're not running it through tools to tell them what they got wrong.
Waiting till they've actually tried to examine it through reflection
lets us throw an exception on code that cares about it rather than
preventing code which ignores reflection from running.

I, for one, am a fan of Java style annotations which allow a string
name plus optional metadata.

@@foo
class Bar {
@@Baz("something", 123, [ 'a', 'b', ''c'])
public function qux() { ... }
}

Though the formality of having to define the annotation as an
interface is a bit overkill for PHP, the same rules Hack uses would be
clear and simple enough:

<<foo>>
class Bar {
<<Baz("something", 123, [ 'a', 'b', 'c'])>>
public function qux() { ... }
}

And no, I'm not picky about the parser symbol used... In fact,
allowing an optional '//' prefix to annotations might be nice for
compatibility.

-Sara

9 years ago by Pedro Cordeiro — view source

unread

I'd really like to see something outside the docblock. Comment annotations
are a workaround for the lack of native annotations. It makes the
environment hard to learn ("What does @param do? And what does @ManyToMany
do?"), it makes it impossible for IDEs to hint/autocomplete without
project-specific plugins, and adds this odd notion that removing some
comment blocks might break an app (which is just awful).

@beberlei, I had searched through the archives already and couldn't find
the vote. I found the discussion (in which many people advocated for
docblock annotations), but didn't find the vote.

I feel like this is a major feature that's missing, and people are using it
in a suboptimal way (docblocks), so I thought I'd reopen the discussion and
see if someone more familiar with the internals feels like implementing it
(I don't feel confident enough since I've never tried messing with into the
internals).

2015-11-24 22:31 GMT-02:00 Sara Golemon pollita@php.net:

On Tue, Nov 24, 2015 at 11:05 AM, Rowan Collins rowan.collins@gmail.com
wrote:

At first sight, these seem like details which could be tweaked later, but
they make a difference to what syntax to standardise: is the annotation
name
just a string, or a valid class name? is the value of the annotation
just a
string, or a parseable PHP expression? is it more useful to use the de
facto
existing syntax in DocBlocks, or to add a new keyword or operator? etc

If we're going to use something in the docblock, then I wouldn't want
it parsed on compilation, but rather have it be an on-demand parse
while reflecting. The reason being that there are plenty of
docblock'd PHP libraries out there using invalid annotations because
they're not running it through tools to tell them what they got wrong.
Waiting till they've actually tried to examine it through reflection
lets us throw an exception on code that cares about it rather than
preventing code which ignores reflection from running.

I, for one, am a fan of Java style annotations which allow a string
name plus optional metadata.

@@foo
class Bar {
@@Baz("something", 123, [ 'a', 'b', ''c'])
public function qux() { ... }
}

Though the formality of having to define the annotation as an
interface is a bit overkill for PHP, the same rules Hack uses would be
clear and simple enough:

<<foo>>
class Bar {
<<Baz("something", 123, [ 'a', 'b', 'c'])>>
public function qux() { ... }
}

And no, I'm not picky about the parser symbol used... In fact,
allowing an optional '//' prefix to annotations might be nice for
compatibility.

-Sara

9 years ago by Lester Caine — view source

unread

I feel like this is a major feature that's missing, and people are using it
in a suboptimal way (docblocks), so I thought I'd reopen the discussion and
see if someone more familiar with the internals feels like implementing it

In previous discussions it was pointed out that a substantial amount of
legacy code already uses docblock style annotation, and that is well
supported by IDE's and other tools, so there is no reason not it
continue to support that substantial base. Any new system would require
every third party tool to be adapted to use it was there any reason to
load the code base with something which will only have a limited uptake.
Adding an extension to provide an alternative would be the correct way
forward, and then if that gains traction, look to it's status then.

--
Lester Caine - G8HFL

Contact - http://lsces.co.uk/wiki/?page=contact
L.S.Caine Electronic Services - http://lsces.co.uk
EnquirySolve - http://enquirysolve.com/
Model Engineers Digital Workshop - http://medw.co.uk
Rainbow Digital Media - http://rainbowdigitalmedia.co.uk

9 years ago by Pedro Cordeiro — view source

unread

2015-11-25 13:47 GMT-02:00 Lester Caine lester@lsces.co.uk:

Any new system would require
every third party tool to be adapted to use it

That's not true at all. A new syntax would in no way invalidate parsing
annotations from docblocks.

The only legacy code that is supported by IDEs (if they are, PHPStorm will
not hint/autocomplete, nor will eclipse/netbeans) would be
Symfony2/Doctrine2. There are tons of other tools that with custom
annotations (JMSSerializer as an example) that do not have any support at
all.

This argument is so flawed that you didn't consider that there are many
parsers with many different syntaxes (
https://github.com/jan-swiecki/php-simple-annotations,
https://github.com/nette/neon) and that ANY implementation, be it through
docblocks or with a native syntax would require a rewrite anyway for many
projects if those tools want to support the new native feature.

Also, doing it through an extension is a nice way to delay adoption,
because shared hosts rarely give the option to install new extensions.

I don't have a vote here, but if I had, I'd strongly oppose any
docblock-based implementation.

9 years ago by Larry Garfield — view source

unread

2015-11-25 13:47 GMT-02:00 Lester Caine lester@lsces.co.uk:

Any new system would require
every third party tool to be adapted to use it

That's not true at all. A new syntax would in no way invalidate parsing
annotations from docblocks.

The only legacy code that is supported by IDEs (if they are, PHPStorm will
not hint/autocomplete, nor will eclipse/netbeans) would be
Symfony2/Doctrine2. There are tons of other tools that with custom
annotations (JMSSerializer as an example) that do not have any support at
all.

This argument is so flawed that you didn't consider that there are many
parsers with many different syntaxes (
https://github.com/jan-swiecki/php-simple-annotations,
https://github.com/nette/neon) and that ANY implementation, be it through
docblocks or with a native syntax would require a rewrite anyway for many
projects if those tools want to support the new native feature.

Also, doing it through an extension is a nice way to delay adoption,
because shared hosts rarely give the option to install new extensions.

I don't have a vote here, but if I had, I'd strongly oppose any
docblock-based implementation.

When Drupal adopted annotations, the absolute #1 objection people had
was "but docblocks aren't code, you moron!" There's no value in
language-native annotations being in the docblock, other than BC with
some existing implementations. However, doing so would make static
checking more difficult; If annotations become a language-native
feature, they should be a first-class citizen to make it easier for IDEs
to handle.

I'm also not super picky on what the tokens are, however I do think
mapping them to actual classes, like Doctrine does, would be the most
flexible. Structured data all the things. That also means annotations
can be namespaced, be affected by use statements, and so forth. In a
sense, they become isomorphic to:

class Foo {
public static function getAnnotations() {
return [
new OneToMany('a', 'b', 'c'),
new Stuff('d', 4);
];
}
}

Except they can be applied to anything reflectable rather than just
classes. (Functions, methods, classes, object properties.)

Sara's suggestion of making them legal within a // comment line for BC
reasons is interesting, but we don't do that for any other new syntax
AFAIK. Plus, it means it's harder to comment out an annotation
temporarily for debugging. There's still /* */, but it's one more quirk
to have to think about.

--
--Larry Garfield

9 years ago by Rowan Collins — view source

unread

Larry Garfield wrote on 25/11/2015 16:42:

However, doing so would make static checking more difficult; If
annotations become a language-native feature, they should be a
first-class citizen to make it easier for IDEs to handle.

Could you explain why docblocks are harder to parse than text outside
docblocks? As far as I know, IDEs already parse docblocks, e.g. using
@param and @return for type analysis, so I don't really see why
generalising that would be a big problem.

9 years ago by Pedro Cordeiro — view source

unread

Rowan, even if they are not harder, there is no reason to keep this feature
in docblocks. Even the argument "compatibility with current
implementations" is flawed, because there are many different
implementations (not only doctrine's) with different syntaxes, so any
native option would break SOME implementations.

Docblocks are Documentation Blocks, which is meant for documentation only.

Mixing documentation (@param) with runtime stuff (@manyToMany) is
counter-intuitive and makes the ecosystem harder to learn.

It's also weird that removing comment blocks break an app.

2015-11-25 14:47 GMT-02:00 Rowan Collins rowan.collins@gmail.com:

Larry Garfield wrote on 25/11/2015 16:42:

However, doing so would make static checking more difficult; If
annotations become a language-native feature, they should be a first-class
citizen to make it easier for IDEs to handle.

Could you explain why docblocks are harder to parse than text outside
docblocks? As far as I know, IDEs already parse docblocks, e.g. using
@param and @return for type analysis, so I don't really see why
generalising that would be a big problem.

9 years ago by Rowan Collins — view source

unread

Pedro Cordeiro wrote on 25/11/2015 16:53:

Rowan, even if they are not harder, there is no reason to keep this
feature in docblocks.

Well, I can think of one reason: backwards compatibility. I don't mean
with current frameworks - as you say, these are not currently
standardised, so some will need to be adapted whatever is implemented in
core - but with older versions of PHP.

If we invent new syntax, then any code using that feature must require
the version of PHP that introduces that syntax, because previous
versions will simply throw a syntax error. There are a few ways around
this, such as:

allowing the annotation to be preceded by // as Sara suggested (or
maybe #, to make it look like a C pre-processor directive)
using some other syntax that is currently a no-op, like ECMAScript's
wacky "use strict"

But ultimately, these end up having the same disadvantages you're
claiming for docblocks - they look like things you can delete, or which
has some other purpose, but are actually vital to the operation of the
code.#

I don't feel that strongly in favour of docblocks, but I don't think the
reasons given against are particularly strong.

Regards,

Rowan Collins
[IMSoP]

9 years ago by guilhermeblanco@gmail.com — view source

unread

Hi,

I'm the co-author of RFC of Annotations, co-author of Annotations in
docblock which I abandoned for being conceptually wrong and co-author of
Doctrine Annotations.

Comments such as the one from Lester Caine "In previous discussions it was
pointed out that a substantial amount of legacy code already uses docblock
style annotation, and that is well supported by IDE's and other tools, so
there is no reason not it continue to support that substantial base." makes
me very sad, specially because these claimed legacy code using docblocks
were only written that way in first place because Annotations RFC got
"declined".

Yes, I quoted because it actually acquired a lot of positive votes (over
50% of overall voters) even when there was no 2/3, 50% +1, etc criteria,
but that's the feedback I received after bothering a lot of people about
patch's resolution: the majority of long period contributors of PHP voted
against the patch considering it was too complex, with several
modifications to Zend Engine, which lead them to reject as it was. I also
got suggested to implement this support outside of core through a PECL
extension parsing docblock annotations.

If ever any "long term contributor" decided to discuss about potentially
introducing Annotations into PHP core, I'll be the first one to help. Until
them, anything userland guys ask here IMHO is irrelevant.

Regards,

On Wed, Nov 25, 2015 at 12:00 PM, Rowan Collins rowan.collins@gmail.com
wrote:

Pedro Cordeiro wrote on 25/11/2015 16:53:

Rowan, even if they are not harder, there is no reason to keep this
feature in docblocks.

Well, I can think of one reason: backwards compatibility. I don't mean
with current frameworks - as you say, these are not currently standardised,
so some will need to be adapted whatever is implemented in core - but with
older versions of PHP.

If we invent new syntax, then any code using that feature must require
the version of PHP that introduces that syntax, because previous versions
will simply throw a syntax error. There are a few ways around this, such as:

allowing the annotation to be preceded by // as Sara suggested (or maybe
#, to make it look like a C pre-processor directive)

using some other syntax that is currently a no-op, like ECMAScript's
wacky "use strict"

But ultimately, these end up having the same disadvantages you're claiming
for docblocks - they look like things you can delete, or which has some
other purpose, but are actually vital to the operation of the code.#

I don't feel that strongly in favour of docblocks, but I don't think the
reasons given against are particularly strong.

Regards,

Rowan Collins
[IMSoP]

--

--
Guilherme Blanco
MSN: guilhermeblanco@hotmail.com
GTalk: guilhermeblanco
Toronto - ON/Canada

9 years ago by Larry Garfield — view source

unread

I don't feel that strongly in favour of docblocks, but I don't think
the reasons given against are particularly strong.

Regards,

If you don't feel strongly in favor of them, why are you trying to make
a case for them so strongly? Just for kicks? We don't need a "devil's
advocate" at this point in the discussion...

--
--Larry Garfield

9 years ago by Rowan Collins — view source

unread

Larry Garfield wrote on 25/11/2015 17:39:

I don't feel that strongly in favour of docblocks, but I don't think
the reasons given against are particularly strong.

Regards,

If you don't feel strongly in favor of them, why are you trying to
make a case for them so strongly? Just for kicks? We don't need a
"devil's advocate" at this point in the discussion...

Hi Larry,

I don't feel strongly in favour or against them, but can see
advantages and disadvantages on both sides. Feeling strongly is not the
same as having a strong argument for your point of view, so just because
some people have expressed strong opinions against, I don't see why I
shouldn't challenge their reasoning, even if that does mean playing
devil's advocate.

Which is better: basing the decision on the gut feeling of a handful of
people who happen to be here now, or basing it on sound reasoning after
thinking through the implications?

Regards,

Rowan Collins
[IMSoP]

9 years ago by guilhermeblanco@gmail.com — view source

unread

I can give you a good argument.

opcache.save_comments=0

Make it work.

On Wed, Nov 25, 2015 at 12:48 PM, Rowan Collins rowan.collins@gmail.com
wrote:

Larry Garfield wrote on 25/11/2015 17:39:

I don't feel that strongly in favour of docblocks, but I don't think the
reasons given against are particularly strong.

Regards,

If you don't feel strongly in favor of them, why are you trying to make a
case for them so strongly? Just for kicks? We don't need a "devil's
advocate" at this point in the discussion...

Hi Larry,

I don't feel strongly in favour or against them, but can see advantages
and disadvantages on both sides. Feeling strongly is not the same as having
a strong argument for your point of view, so just because some people have
expressed strong opinions against, I don't see why I shouldn't challenge
their reasoning, even if that does mean playing devil's advocate.

Which is better: basing the decision on the gut feeling of a handful of
people who happen to be here now, or basing it on sound reasoning after
thinking through the implications?

Regards,

Rowan Collins
[IMSoP]

--

--
Guilherme Blanco
MSN: guilhermeblanco@hotmail.com
GTalk: guilhermeblanco
Toronto - ON/Canada

9 years ago by Rowan Collins — view source

unread

guilhermeblanco@gmail.com wrote on 25/11/2015 17:58:

I can give you a good argument.

opcache.save_comments=0

Make it work.

Simple: remove that configuration variable, and always save doc blocks.
As mentioned, my view would be that these should no longer be considered
"comments", but "metadata", and that documentation and core features
would be altered to reflect this.

Did you think that was a killer argument, or just another thought to
bring to the discussion? Because I absolutely welcome people adding to
the list of pros and cons on either side, but I object to any attempt
to shut down the discussion just because people have already made their
mind up based on some gut feeling.

Regards,

Rowan Collins
[IMSoP]

9 years ago by Rowan Collins — view source

unread

Rowan Collins wrote on 25/11/2015 18:47:

Simple: remove that configuration variable, and always save doc blocks.

Thinking about it, you don't even need to do that, just add a structure
in the opcache memory layout for the parsed annotations, allowing you to
accelerate access to those. (Something you'd have to do anyway if the
syntax was outside the docblock.)

9 years ago by Pedro Cordeiro — view source

unread

On top of it, it'd break obfuscators like Zend Guard.

2015-11-25 15:58 GMT-02:00 guilhermeblanco@gmail.com <
guilhermeblanco@gmail.com>:

I can give you a good argument.

opcache.save_comments=0

Make it work.

On Wed, Nov 25, 2015 at 12:48 PM, Rowan Collins rowan.collins@gmail.com
wrote:

Larry Garfield wrote on 25/11/2015 17:39:

I don't feel that strongly in favour of docblocks, but I don't think
the
reasons given against are particularly strong.

Regards,

If you don't feel strongly in favor of them, why are you trying to make
a
case for them so strongly? Just for kicks? We don't need a "devil's
advocate" at this point in the discussion...

Hi Larry,

I don't feel strongly in favour or against them, but can see advantages
and disadvantages on both sides. Feeling strongly is not the same as
having
a strong argument for your point of view, so just because some people
have
expressed strong opinions against, I don't see why I shouldn't challenge
their reasoning, even if that does mean playing devil's advocate.

Which is better: basing the decision on the gut feeling of a handful of
people who happen to be here now, or basing it on sound reasoning after
thinking through the implications?

Regards,

Rowan Collins
[IMSoP]

--

--
Guilherme Blanco
MSN: guilhermeblanco@hotmail.com
GTalk: guilhermeblanco
Toronto - ON/Canada

9 years ago by guilhermeblanco@gmail.com — view source

unread

Hi Rowan,

If you're in a shared hosting, you can't "simply" remove the configuration
variable.
Relying on extensions or configuration flags to support core language
features is very bad. We don't have flags that can turn IF support off for
example, why we would have that for annotations?
I can bring more cons if you want... like how/when to parse "use" calls in
a docblock? I mainly want to address the need of this class:
https://github.com/doctrine/annotations/blob/master/lib/Doctrine/Common/Annotations/TokenParser.php

I've exhausted to death pros and cons of every single part. The biggest
problem of not realizing this is a core feature and pushing so hard to
docblock is that as soon as this is blinded to some people, others will say
"oh, so that doesn't need to be in core and can be a PECL extension". Now
re-read my email from the beginning about shared hosting, you just entered
in an infinite loop.

On Wed, Nov 25, 2015 at 1:50 PM, Pedro Cordeiro pedronaroga@gmail.com
wrote:

On top of it, it'd break obfuscators like Zend Guard.

2015-11-25 15:58 GMT-02:00 guilhermeblanco@gmail.com <
guilhermeblanco@gmail.com>:

I can give you a good argument.

opcache.save_comments=0

Make it work.

On Wed, Nov 25, 2015 at 12:48 PM, Rowan Collins rowan.collins@gmail.com
wrote:

Larry Garfield wrote on 25/11/2015 17:39:

I don't feel that strongly in favour of docblocks, but I don't think
the
reasons given against are particularly strong.

Regards,

If you don't feel strongly in favor of them, why are you trying to
make a
case for them so strongly? Just for kicks? We don't need a "devil's
advocate" at this point in the discussion...

Hi Larry,

I don't feel strongly in favour or against them, but can see
advantages
and disadvantages on both sides. Feeling strongly is not the same as
having
a strong argument for your point of view, so just because some people
have
expressed strong opinions against, I don't see why I shouldn't challenge
their reasoning, even if that does mean playing devil's advocate.

Which is better: basing the decision on the gut feeling of a handful of
people who happen to be here now, or basing it on sound reasoning after
thinking through the implications?

Regards,

Rowan Collins
[IMSoP]

--

--
Guilherme Blanco
MSN: guilhermeblanco@hotmail.com
GTalk: guilhermeblanco
Toronto - ON/Canada

--
Guilherme Blanco
MSN: guilhermeblanco@hotmail.com
GTalk: guilhermeblanco
Toronto - ON/Canada

9 years ago by Rowan Collins — view source

unread

Hi Rowan,

If you're in a shared hosting, you can't "simply" remove the
configuration
variable.
Relying on extensions or configuration flags to support core language
features is very bad. We don't have flags that can turn IF support off
for
example, why we would have that for annotations?

I think you misunderstood: I didn't mean that users would need to turn that feature off, I meant that that feature would be removed, and docblocks would always be saved.

I can bring more cons if you want... like how/when to parse "use" calls
in
a docblock

In exactly the same place you'd parse them outside a docblock.

I really don't understand all these arguments about the parsing being harder. The only difference is that you're parsing /** @Foo */ instead of <<Foo>> or whatever other syntax anyone comes up with.

Really the only difference is that a docblock means sharing with other metadata (directives for generating documentation). Which has the advantage of being polyfillable from older versions of PHP, but the disadvantage of not being as clearly separated as a new type of syntax. Oh, and the perception, right or wrong, that docblocks are "just comments", rather than metadata containers, which Drupal's experience may demonstrate is more important than a purely rational analysis would suggest.

All the other details about how this or that tool will adapt, how whitespace and multiline values should be handled, etc, are going to need just as much thought whatever the syntax looks like.

Regards,

--
Rowan Collins
[IMSoP]

9 years ago by guilhermeblanco@gmail.com — view source

unread

Ok, so I'll explain why it's not "the same way" as you imagine.

I've heard this many times already so I'll save you keystrokes.

"Sure, we can do that on docblocks"
"Based on that, it doesn't need to be part of core and can safely be
implemented as a PECL extension"

IMHO, internals need to stop considering that PECL is a space for beta
testing features, 95% of userland doesn't even know what PECL is.

Now back to business. At parsing level, PHP has its own parser which we
could take advantage of, and though PECL extension would have to create
one. Clearly not the same way.

The closest stage we can start with this at parsed and resolved AST level
(or enter on the dark side of PHP rewriting stuff like xdebug does).
At that stage, we'd already have resolved classnames, but not for those
annotations in docblock, which is a simple block of text so far. We'd also
have to introspect the AST before it pushes to zend_compile, where use
states are vanished and all classes are already string-resolved into their
corresponding FQCN. And we still have to resolve the class names in the
docblocks using USE statements at AST level, we don't even have the
zend_class_entry instances done at that point, because they're only built
later. Not the same way, again.

Considering I've resolved these problems, it starts wit managing these data
structures. At AST level, we don't have the zend_class_entries, but I'd
already be forced to create instances of specific annotation instances. And
also I need to manage keeping my own data structures, cache them through
opcode and also implement/override Reflection data structures to enable
access to specific annotated elements. Still not the same thing.

Now let's enter on logistics of parsing the docblock text. It's multi-lined
and parsing strings like the one I sent you as an example that you ignored
to answer me back replying "it's just the same way" of parsing now need to
be away of line and column location and carefully remove pieces of text
(remember the " * " I commented?), leading to unexpected behavior and
potentially removing user's text, while re2c would already have done for
us. Again, not the same way.

I can't even imagine how can you bindly say the implementation would be the
same or act the same way as a docblock implementation. It's incredibly
complex, error prone and unreliable to be ensured present (well, it'd be an
optional extension, right?) for such an intrinsic to the language data
structure. We didn't make namespaces a PECL extension, we didn't make
traits part of docblocks. I'd argue traits is not widely used too and the
introduced complexity to core was very big. It could easily be solved by
"using traits" through docblocks and general classes too. Why your argument
is applicable to one thing and not the other?

If anyone is really willing to actually discuss true annotations
implementation and behavior in core, I'm here to help. Until then, I'll
keep watching the list.
Ah, and please stop saying "it should be in docblock". This argument is
just bull... to suppress the actual people interested to see this natively
available and just exposes your lack of interest into language improvement.

Regards,

On Wed, Nov 25, 2015 at 5:03 PM, Rowan Collins rowan.collins@gmail.com
wrote:

On 25 November 2015 19:02:37 GMT, "guilhermeblanco@gmail.com" <
guilhermeblanco@gmail.com> wrote:

Hi Rowan,

If you're in a shared hosting, you can't "simply" remove the
configuration
variable.
Relying on extensions or configuration flags to support core language
features is very bad. We don't have flags that can turn IF support off
for
example, why we would have that for annotations?

I think you misunderstood: I didn't mean that users would need to turn
that feature off, I meant that that feature would be removed, and docblocks
would always be saved.

I can bring more cons if you want... like how/when to parse "use" calls
in
a docblock

In exactly the same place you'd parse them outside a docblock.

I really don't understand all these arguments about the parsing being
harder. The only difference is that you're parsing /** @Foo */ instead of
<<Foo>> or whatever other syntax anyone comes up with.

Really the only difference is that a docblock means sharing with other
metadata (directives for generating documentation). Which has the advantage
of being polyfillable from older versions of PHP, but the disadvantage of
not being as clearly separated as a new type of syntax. Oh, and the
perception, right or wrong, that docblocks are "just comments", rather than
metadata containers, which Drupal's experience may demonstrate is more
important than a purely rational analysis would suggest.

All the other details about how this or that tool will adapt, how
whitespace and multiline values should be handled, etc, are going to need
just as much thought whatever the syntax looks like.

Regards,

--
Rowan Collins
[IMSoP]

--

--
Guilherme Blanco
MSN: guilhermeblanco@hotmail.com
GTalk: guilhermeblanco
Toronto - ON/Canada

9 years ago by Rowan Collins — view source

unread

guilhermeblanco@gmail.com wrote on 26/11/2015 01:13:

Ok, so I'll explain why it's not "the same way" as you imagine.

I've heard this many times already so I'll save you keystrokes.

"Sure, we can do that on docblocks"

"Based on that, it doesn't need to be part of core and can safely be
implemented as a PECL extension"

OK, as far as everything I was talking about, this is all rather a straw
man, but perhaps that's just a miscommunication on my part, so let me
clear that up:

I have never suggested, and would not support a suggestion, that this be
implemented as an extension. I can absolutely see the advantage to
having a first-class syntax, baked into the main parser.

With that out of the way, we are back to the main point I was trying to
make which is that that syntax could, if we wanted, live inside the
context of /** */ blocks, which are already treated differently from
comments. The parsing problems within that context are very similar to
the parsing problems in any other context (again, assuming that this is
being implemented directly in the core parser, not in any kind of
extension).

So, the pros and cons of that are not to do with the parsing but to do with:

potential compatibility with existing code, which may be tricky as
there is no standard to base the feature on
the ability to polyfill code in older PHP versions, which is useful
but not something we have aimed for with previous features
on the other side, the perception that docblocks are "just comments",
which would be hard to dispel even if we renamed them "metadata blocks"

Anyway, I apologise for drawing out this part of the discussion for so
long. I actually think it's just one of many decisions that needs making
before this feature can be attempted, probably starting with just what
an annotation consists of - is it a label with some text attached? a
resolved class name with parsed PHP code passed to its constructor (some
people have mentioned arrays and heredocs as parameters to annotations)?
somewhere between the two?

Regards,

Rowan Collins
[IMSoP]

9 years ago by Pedro Cordeiro — view source

unread

Hi, Rowan. I'll respond to some points that have become recurrent.

It's might not be objectively bad to add this feature in docblocks, but
it will be objectively wrong to keep calling them "DocBlocks" if they are
no longer documentation-only blocks.
Even though PHP already treats docblocks differently from comments,
that's not the common view on userland, nor is explained on the manuals.
There are no separate entries to explain docblocks, and no mention to them
on the "Comments" page. The Reflection method to retrieve DocBlocks is
"getDocCOMMENT", which suggests they are comment that do not affect runtime
behaviour.

We'd have to update the comments page to say "'/' starts a comment, unless
if they're immediately followed by another asterisk ('/*'), in which case
it may or may not be a comment, depends on the following token". It's very
confusing.

To make this work within docblocks, we'd have to get rid of at least one
configuration setting (opcode.save_comments).
You've suggested disregarding docblock stripping from transpilers and
obfuscators, because they are not first-class citizens, even though those
are part of the PHP ecosystem and affect users.
We'd have a harder time making decisions on syntax for docblocks,
because there are already multiple different implementations, and because
people will have a hard time agreeing on some points, like the one
guilherme made about the asterisks (*) or spaces being part of multiline
annotation or not.

Whereas none of these points are issues for a native syntax outside
docblocks, because it'd be a completely different feature that would reside
in new syntax, not in modification of current syntax.

2015-11-26 8:06 GMT-02:00 Rowan Collins rowan.collins@gmail.com:

guilhermeblanco@gmail.com wrote on 26/11/2015 01:13:

Ok, so I'll explain why it's not "the same way" as you imagine.

I've heard this many times already so I'll save you keystrokes.

"Sure, we can do that on docblocks"

"Based on that, it doesn't need to be part of core and can safely be
implemented as a PECL extension"

OK, as far as everything I was talking about, this is all rather a straw
man, but perhaps that's just a miscommunication on my part, so let me clear
that up:

I have never suggested, and would not support a suggestion, that this be
implemented as an extension. I can absolutely see the advantage to having a
first-class syntax, baked into the main parser.

With that out of the way, we are back to the main point I was trying to
make which is that that syntax could, if we wanted, live inside the context
of /** */ blocks, which are already treated differently from comments. The
parsing problems within that context are very similar to the parsing
problems in any other context (again, assuming that this is being
implemented directly in the core parser, not in any kind of extension).

So, the pros and cons of that are not to do with the parsing but to do
with:

potential compatibility with existing code, which may be tricky as there
is no standard to base the feature on

the ability to polyfill code in older PHP versions, which is useful but
not something we have aimed for with previous features

on the other side, the perception that docblocks are "just comments",
which would be hard to dispel even if we renamed them "metadata blocks"

Anyway, I apologise for drawing out this part of the discussion for so
long. I actually think it's just one of many decisions that needs making
before this feature can be attempted, probably starting with just what an
annotation consists of - is it a label with some text attached? a resolved
class name with parsed PHP code passed to its constructor (some people have
mentioned arrays and heredocs as parameters to annotations)? somewhere
between the two?

Regards,

Rowan Collins
[IMSoP]

9 years ago by Rowan Collins — view source

unread

Hi Pedro,

I agree with most of the points in your last mail. At the end of the
day, the reasons are fairly subjective, and relate to how the feature
will be perceived, and the freedom to design it without annoying people,
but that doesn't stop them being real.

However I would like to come back on this one:

Pedro Cordeiro wrote on 26/11/2015 11:46:

You've suggested disregarding docblock stripping from transpilers
and obfuscators, because they are not first-class citizens, even
though those are part of the PHP ecosystem and affect users.

You're putting words into my mouth there; I never said to disregard the
tools themselves, I disputed that they will be disadvantaged by one
syntax over another.

Transpilers and obfuscators will have to make changes either way, if
they are to support annotations; the nature of those changes is
different inside and outside docblocks, but that doesn't seem that big a
deal to me. Whatever the syntax, they will have to do two things: 1)
parse the source code for annotations, adding them to whatever AST or
similar they use; 2) output those annotations (with any relevant
transforms) in the appropriate syntax. I don't see /** @Foo(42) */ as
fundamentally harder to do that with than << Foo(42) >>, or whatever
other syntax anyone comes up with.

Other than this point, this e-mail is a much better summary of why
docblocks should not be used than any details about which of two
syntaxes (that we haven't invented yet) parsers might or might not find
harder.

As I say, apologies for side-tracking the conversation for so long, I
was intending it to be one decision among many, and wanted to make sure
we'd captured a good reason for the decision, so that it could be
justified in future.

Regards,

Rowan Collins
[IMSoP]

9 years ago by Pedro Cordeiro — view source

unread

Hey, Rowan, don't apologize for making the case for what you believed to be
the right way. I'm glad I could summarize my views in a way that you could
agree with me.

I've reread your point about the transpilers and obfuscators, and you're
right, I misunderstood what you said. I'm sorry.

Now, I'd be willing to create a new RFC draft for a native annotation
syntax, targeted at 7.1, this time explaining the reasons NOT to do this in
docblocks nor in a seperate extension, so the discussion won't get
sidetracked again. I'd need some help with the patches, though, since I
don't have any experience with the internals.

There is still the issue of complexity added to the engine, which we could
discuss. I'd like to hear more from a long-term contributor about that, if
it's possible. Were there any performance implications on the previously
submitted patch?

Thank you everyone for the great discussion.

9 years ago by Levi Morrison — view source

unread

Ah, and please stop saying "it should be in docblock". This argument is
just bull... to suppress the actual people interested to see this natively
available and just exposes your lack of interest into language improvement.

Every feature has a cost and benefit. It is perfectly fine to have the
opinion that a feature is better left out of the language based on
that cost. Being against a feature does not mean that person is
against language improvement or has a lack of interest.

9 years ago by guilhermeblanco@gmail.com — view source

unread

Let's be clear. I haven't seen any user asking for traits, which introduced
almost the same amount of performance cost and complexity to ZE. It was
proposed by a "long term contributor" and everybody said yay.

When multiple userland people ask about the same feature, every single
major framework uses a hackish way to suppress a language deficiency, and
internals developers don't move a finger (or even care to reply here) about
the subject, it clearly exposes to me they're not paying attention to
user's needs. This is lack of interest, but you can choose better words.

Regards,

Ah, and please stop saying "it should be in docblock". This argument is
just bull... to suppress the actual people interested to see this
natively
available and just exposes your lack of interest into language
improvement.

Every feature has a cost and benefit. It is perfectly fine to have the
opinion that a feature is better left out of the language based on
that cost. Being against a feature does not mean that person is
against language improvement or has a lack of interest.

--
Guilherme Blanco
MSN: guilhermeblanco@hotmail.com
GTalk: guilhermeblanco
Toronto - ON/Canada

9 years ago by Rowan Collins — view source

unread

guilhermeblanco@gmail.com wrote on 26/11/2015 15:14:

I haven't seen any user asking for traits

Just because you didn't see it, doesn't mean it didn't happen.

I just did a very quick search on Google for php + mixins, limited to
2007 or earlier (long before the current Trait implementation was born),
and got plenty of results lamenting the lack of support for horizontal
reuse in PHP.

See for yourself:
https://encrypted.google.com/search?q=php+%22horizontal+reuse%22&safe=active&hl=en&source=lnt&tbs=cdr%3A1%2Ccd_min%3A%2Ccd_max%3A12%2F31%2F2007&tbm=#safe=active&hl=en&tbs=cdr:1%2Ccd_max:12%2F31%2F2007&q=php+mixins

It's a common accusation of projects like this that time was spent on X
that should have been spent on Y, but that's nearly always a massive
over-simplification.

Let's not spend too much time worrying if specific people are interested

they may just be on holiday, or busy elsewhere, or just not have much
to say until someone assembles a few more details about the proposed
feature. Keep it constructive, lay out how you think the feature should
look and why, what questions are still open, and see what's needed to
move it forward.

Regards,

Rowan Collins
[IMSoP]

9 years ago by guilhermeblanco@gmail.com — view source

unread

Ok then. I'll pretend that lack of interest didn't happen many other
situations (like http://marc.info/?t=144608767800001) and move on.

I don't want to bring the patch up to date/simplify it without a clear
decision of at least be willing to discuss the patch and not reject by all
means.
I'd propose a voting as "Are you ready for Annotations yet?". Every core
developer understands (and can base their decisions) by looking at the
complexity of the old patch.

Once voting completes and IF it gets approved, I'll gladly put it up to
date for consideration and update the RFC.

[]s,

On Thu, Nov 26, 2015 at 10:53 AM, Rowan Collins rowan.collins@gmail.com
wrote:

guilhermeblanco@gmail.com wrote on 26/11/2015 15:14:

I haven't seen any user asking for traits

Just because you didn't see it, doesn't mean it didn't happen.

I just did a very quick search on Google for php + mixins, limited to 2007
or earlier (long before the current Trait implementation was born), and got
plenty of results lamenting the lack of support for horizontal reuse in PHP.

See for yourself:
https://encrypted.google.com/search?q=php+%22horizontal+reuse%22&safe=active&hl=en&source=lnt&tbs=cdr%3A1%2Ccd_min%3A%2Ccd_max%3A12%2F31%2F2007&tbm=#safe=active&hl=en&tbs=cdr:1%2Ccd_max:12%2F31%2F2007&q=php+mixins

It's a common accusation of projects like this that time was spent on X
that should have been spent on Y, but that's nearly always a massive
over-simplification.

Let's not spend too much time worrying if specific people are interested -
they may just be on holiday, or busy elsewhere, or just not have much to
say until someone assembles a few more details about the proposed feature.
Keep it constructive, lay out how you think the feature should look and
why, what questions are still open, and see what's needed to move it
forward.

Regards,

Rowan Collins
[IMSoP]

--

--
Guilherme Blanco
MSN: guilhermeblanco@hotmail.com
GTalk: guilhermeblanco
Toronto - ON/Canada

9 years ago by Rowan Collins — view source

unread

guilhermeblanco@gmail.com wrote on 26/11/2015 16:05:

Ok then. I'll pretend that lack of interest didn't happen many other
situations (like http://marc.info/?t=144608767800001) and move on.

It's possible that a lot of the core devs are still concentrating on
getting the changes in 7.0 bedded in, and have more time to discuss
features for 7.1 in a month or two.

9 years ago by Levi Morrison — view source

unread

guilhermeblanco@gmail.com wrote on 26/11/2015 16:05:

Ok then. I'll pretend that lack of interest didn't happen many other
situations (like http://marc.info/?t=144608767800001) and move on.

It's possible that a lot of the core devs are still concentrating on getting
the changes in 7.0 bedded in, and have more time to discuss features for 7.1
in a month or two.

At least a few are working on features of their own.

I am curious – a quick scan of this thread didn't seem to actually
propose anything new. It's just discussion about same RFC that was
already rejected. Correct?

9 years ago by Pedro Cordeiro — view source

unread

Levi, I was asking about the reasons it was rejected. While researching, I
found the original RFC was voted with 123 votes (71% approval), and yet was
marked as 'declined'. I didn't know why, couldn't find why, so I figured
I'd ask (as it strikes me as a major feature that's missing).

2015-11-26 15:11 GMT-02:00 Levi Morrison levim@php.net:

On Thu, Nov 26, 2015 at 9:57 AM, Rowan Collins rowan.collins@gmail.com
wrote:

guilhermeblanco@gmail.com wrote on 26/11/2015 16:05:

Ok then. I'll pretend that lack of interest didn't happen many other
situations (like http://marc.info/?t=144608767800001) and move on.

It's possible that a lot of the core devs are still concentrating on
getting
the changes in 7.0 bedded in, and have more time to discuss features for
7.1
in a month or two.

At least a few are working on features of their own.

I am curious – a quick scan of this thread didn't seem to actually
propose anything new. It's just discussion about same RFC that was
already rejected. Correct?

9 years ago by Chris Riley — view source

unread

On 26 November 2015 at 16:05, guilhermeblanco@gmail.com <
guilhermeblanco@gmail.com> wrote:

Ok then. I'll pretend that lack of interest didn't happen many other
situations (like http://marc.info/?t=144608767800001) and move on.

I don't want to bring the patch up to date/simplify it without a clear
decision of at least be willing to discuss the patch and not reject by all
means.
I'd propose a voting as "Are you ready for Annotations yet?". Every core
developer understands (and can base their decisions) by looking at the
complexity of the old patch.

Once voting completes and IF it gets approved, I'll gladly put it up to
date for consideration and update the RFC.

[]s,

On Thu, Nov 26, 2015 at 10:53 AM, Rowan Collins rowan.collins@gmail.com
wrote:

guilhermeblanco@gmail.com wrote on 26/11/2015 15:14:

I haven't seen any user asking for traits

Just because you didn't see it, doesn't mean it didn't happen.

I just did a very quick search on Google for php + mixins, limited to
2007
or earlier (long before the current Trait implementation was born), and
got
plenty of results lamenting the lack of support for horizontal reuse in
PHP.

See for yourself:

https://encrypted.google.com/search?q=php+%22horizontal+reuse%22&safe=active&hl=en&source=lnt&tbs=cdr%3A1%2Ccd_min%3A%2Ccd_max%3A12%2F31%2F2007&tbm=#safe=active&hl=en&tbs=cdr:1%2Ccd_max:12%2F31%2F2007&q=php+mixins

It's a common accusation of projects like this that time was spent on X
that should have been spent on Y, but that's nearly always a massive
over-simplification.

Let's not spend too much time worrying if specific people are interested

they may just be on holiday, or busy elsewhere, or just not have much to
say until someone assembles a few more details about the proposed
feature.
Keep it constructive, lay out how you think the feature should look and
why, what questions are still open, and see what's needed to move it
forward.

Regards,

Rowan Collins
[IMSoP]

--

--
Guilherme Blanco
MSN: guilhermeblanco@hotmail.com
GTalk: guilhermeblanco
Toronto - ON/Canada

Given that a lot of userland people have voting rights; I would suspect
that an annotations rfc would pass, provided it met the needs of these
users. As far as docblocks vs native goes - you've convinced me that native
would be best, previously I'd have been more in favour of adding a
getAnnotations method to ReflectionClass/Method/Property, to pull in
annotations from docblocks.

I'd like to see this goto a new RFC here are some questions though:

Can annotations be applied to functions?
Class constants?
Should annotations be a special type eg annotation Foo{} or just a class?
Do we want to add decorator support at the same time? (
http://thecodeship.com/patterns/guide-to-python-function-decorators/)

9 years ago by guilhermeblanco@gmail.com — view source

unread

Answers inline

On 26 November 2015 at 16:05, guilhermeblanco@gmail.com <
guilhermeblanco@gmail.com> wrote:

Ok then. I'll pretend that lack of interest didn't happen many other
situations (like http://marc.info/?t=144608767800001) and move on.

I don't want to bring the patch up to date/simplify it without a clear
decision of at least be willing to discuss the patch and not reject by all
means.
I'd propose a voting as "Are you ready for Annotations yet?". Every core
developer understands (and can base their decisions) by looking at the
complexity of the old patch.

Once voting completes and IF it gets approved, I'll gladly put it up to
date for consideration and update the RFC.

[]s,

On Thu, Nov 26, 2015 at 10:53 AM, Rowan Collins rowan.collins@gmail.com
wrote:

guilhermeblanco@gmail.com wrote on 26/11/2015 15:14:

I haven't seen any user asking for traits

Just because you didn't see it, doesn't mean it didn't happen.

I just did a very quick search on Google for php + mixins, limited to
2007
or earlier (long before the current Trait implementation was born), and
got
plenty of results lamenting the lack of support for horizontal reuse in
PHP.

See for yourself:

https://encrypted.google.com/search?q=php+%22horizontal+reuse%22&safe=active&hl=en&source=lnt&tbs=cdr%3A1%2Ccd_min%3A%2Ccd_max%3A12%2F31%2F2007&tbm=#safe=active&hl=en&tbs=cdr:1%2Ccd_max:12%2F31%2F2007&q=php+mixins

It's a common accusation of projects like this that time was spent on X
that should have been spent on Y, but that's nearly always a massive
over-simplification.

Let's not spend too much time worrying if specific people are
interested -
they may just be on holiday, or busy elsewhere, or just not have much to
say until someone assembles a few more details about the proposed
feature.
Keep it constructive, lay out how you think the feature should look and
why, what questions are still open, and see what's needed to move it
forward.

Regards,

Rowan Collins
[IMSoP]

--

--
Guilherme Blanco
MSN: guilhermeblanco@hotmail.com
GTalk: guilhermeblanco
Toronto - ON/Canada

Given that a lot of userland people have voting rights; I would suspect
that an annotations rfc would pass, provided it met the needs of these
users. As far as docblocks vs native goes - you've convinced me that native
would be best, previously I'd have been more in favour of adding a
getAnnotations method to ReflectionClass/Method/Property, to pull in
annotations from docblocks.

I'd like to see this goto a new RFC here are some questions though:

Can annotations be applied to functions?

Yes, classes, interfaces, traits, methods, properties, functions.
Unfortunately we can't apply to namespaces as they don't exist after
compile time.

Class constants?

No, there's no Reflection data structure around them and imposing one would
be a serious BC break

Should annotations be a special type eg annotation Foo{} or just a class?

Annotation classes would be annotated with @Annotation and their
corresponding @Target (where they could be applied).

Do we want to add decorator support at the same time? (
http://thecodeship.com/patterns/guide-to-python-function-decorators/)

No. Annotations by itself is already a big endeavor and including more
stuff would only make it harder to implement/digest/approve.
What if Annotation gets approved, but people want decorator out? More
work...
Nothing prevent us to make a subsequent RFC to support decorators if the
first one gets accepted.

Regards,

--
Guilherme Blanco
MSN: guilhermeblanco@hotmail.com
GTalk: guilhermeblanco
Toronto - ON/Canada

9 years ago by Larry Garfield — view source

unread

Larry Garfield wrote on 25/11/2015 17:39:

I don't feel that strongly in favour of docblocks, but I don't think
the reasons given against are particularly strong.

Regards,

If you don't feel strongly in favor of them, why are you trying to
make a case for them so strongly? Just for kicks? We don't need a
"devil's advocate" at this point in the discussion...

Hi Larry,

I don't feel strongly in favour or against them, but can see
advantages and disadvantages on both sides. Feeling strongly is not
the same as having a strong argument for your point of view, so just
because some people have expressed strong opinions against, I don't
see why I shouldn't challenge their reasoning, even if that does mean
playing devil's advocate.

Which is better: basing the decision on the gut feeling of a handful
of people who happen to be here now, or basing it on sound reasoning
after thinking through the implications?

Regards,

So far, the only argument FOR them is BC with existing practices.
Everything else I've seen is, I think, ways around the issues that
raises. However, as has been noted the BC is spurious as it would only
be BC with one implementation out of several, and we've never polyfiled
other syntax-level features that I can recall. (We've polyfilled new
functions, but that's easy.)

By the same argument, we should have used docblocks for scalar types,
too, so that they could be polyfilled and be BC with existing practices,
and those would have even been fairly standardized already. Someone
even made that point, IIRC, and it was quickly rejected.

Whereas as a stand-alone syntax, it offers a much better distinction
between "metadata that affects code execution" and "stuff for humans to
read" (both for parsers and for humans). It gives us much more
flexibility to implement a meaningful API. It completely avoids the
"but comments shouldn't be code" question (which is a bigger deal than
you'd think; it was one of the drivers behind the Backdrop fork of
Drupal. I'm not kidding.)

That one of the lead authors of the most widely used comment-based
annotation system in PHP is arguing what a terrible idea a comment-based
annotation system is should carry a great deal of weight.

--
--Larry Garfield

9 years ago by guilhermeblanco@gmail.com — view source

unread

Hi Rowan,

I'm avoiding drilling down as much as I can to explain every single
decision motivation of the 2010's patch, which hints every time why
docblocks are bad.
Maybe another example may help you to illustrate the problem; all I want is
to add a multi-lined text in an annotation (using your docblock approach):

/**

@Documentation\Description("This
is
multi-lined.")
*/

Or:

/**

@Documentation\Description(<<<EOF
This
is
multi-lined
EOF;)
*/

Quickly answer me if every line's * should be part of the string or not. If
not, what about the space after them? How should heredoc work in this case?
Feel free to detail your answers and provide examples.
Things are not as simple as it looks, unfortunately... =(

On Wed, Nov 25, 2015 at 2:16 PM, Larry Garfield larry@garfieldtech.com
wrote:

Larry Garfield wrote on 25/11/2015 17:39:

I don't feel that strongly in favour of docblocks, but I don't think
the reasons given against are particularly strong.

Regards,

If you don't feel strongly in favor of them, why are you trying to make
a case for them so strongly? Just for kicks? We don't need a "devil's
advocate" at this point in the discussion...

Hi Larry,

I don't feel strongly in favour or against them, but can see advantages
and disadvantages on both sides. Feeling strongly is not the same as having
a strong argument for your point of view, so just because some people have
expressed strong opinions against, I don't see why I shouldn't challenge
their reasoning, even if that does mean playing devil's advocate.

Which is better: basing the decision on the gut feeling of a handful of
people who happen to be here now, or basing it on sound reasoning after
thinking through the implications?

Regards,

So far, the only argument FOR them is BC with existing practices.
Everything else I've seen is, I think, ways around the issues that raises.
However, as has been noted the BC is spurious as it would only be BC with
one implementation out of several, and we've never polyfiled other
syntax-level features that I can recall. (We've polyfilled new functions,
but that's easy.)

By the same argument, we should have used docblocks for scalar types, too,
so that they could be polyfilled and be BC with existing practices, and
those would have even been fairly standardized already. Someone even made
that point, IIRC, and it was quickly rejected.

Whereas as a stand-alone syntax, it offers a much better distinction
between "metadata that affects code execution" and "stuff for humans to
read" (both for parsers and for humans). It gives us much more flexibility
to implement a meaningful API. It completely avoids the "but comments
shouldn't be code" question (which is a bigger deal than you'd think; it
was one of the drivers behind the Backdrop fork of Drupal. I'm not kidding.)

That one of the lead authors of the most widely used comment-based
annotation system in PHP is arguing what a terrible idea a comment-based
annotation system is should carry a great deal of weight.

--
--Larry Garfield

--

--
Guilherme Blanco
MSN: guilhermeblanco@hotmail.com
GTalk: guilhermeblanco
Toronto - ON/Canada

9 years ago by Larry Garfield — view source

unread

Larry Garfield wrote on 25/11/2015 16:42:

However, doing so would make static checking more difficult; If
annotations become a language-native feature, they should be a
first-class citizen to make it easier for IDEs to handle.

Could you explain why docblocks are harder to parse than text outside
docblocks? As far as I know, IDEs already parse docblocks, e.g.
using @param and @return for type analysis, so I don't really see why
generalising that would be a big problem.

Not being an IDE author I cannot say for certain, so perhaps it's easier
than I imagine. However, speaking as a user I would want a robust level
of static syntax validation of my annotations. Having robust syntax
validation show up in some parts of my docblock but not others is
confusing for me as a user; I hypothesize that it would similarly be
more difficult to selectively treat bits and pieces of the docblock as
code but not others. (My current IDE, PHPStorm, parses a docblock to
validate that it matches the method signature but all it does is tell me
if the whole thing is valid or not, and if I'm using a "used" class
name. It's actually very unhelpful when dealing with complex Doctrine
annotations like Drupal uses.)

Too, it means that a given annotation directive may have spurious *
characters inside its string, if it's multi-line. Sure, that can be
filtered out (Doctrine already does), but that's one more complication
to have to consider.

For me, the "sometimes it's code and sometimes it's not, even though it
looks the same" argument is sufficient to reject docblocks as a location
for annotations.

--
--Larry Garfield

9 years ago by Rowan Collins — view source

unread

Larry Garfield wrote on 25/11/2015 17:06:

Too, it means that a given annotation directive may have spurious *
characters inside its string, if it's multi-line. Sure, that can be
filtered out (Doctrine already does), but that's one more complication
to have to consider.

I would expect that behaviour would be part of the standard definition,
and the core implementation, so don't really see it as a big deal. The
same thing happens with leading whitespace in many syntaxes anyway.

9 years ago by Rowan Collins — view source

unread

Larry Garfield wrote on 25/11/2015 17:06:

For me, the "sometimes it's code and sometimes it's not, even though
it looks the same" argument is sufficient to reject docblocks as a
location for annotations.

Annotations aren't code, they're metadata, and docblocks already contain
metadata; it's just that originally, that metadata was targeted at
generating documentation, rather than generating code, or affecting
run-time behaviour.

9 years ago by Rowan Collins — view source

unread

Pedro Cordeiro wrote on 25/11/2015 11:04:

I'd really like to see something outside the docblock. Comment
annotations are a workaround for the lack of native annotations.

This is true, but they are now a very widely used workaround, and any
native support for them could be polyfilled using the kind of userland
libraries that already exist.

It makes the environment hard to learn ("What does @param do? And what
does @ManyToMany do?")

I'm not sure how this is made any easier by moving the annotations out
of the docblock. I suppose it's a little confusing that, within the
docblock, code annotations and documentation annotations share the same
syntax; maybe we could use a different prefix, like "@@" instead of "@"?
This would also give a chance for projects to transition to the new
standard syntax, rather than having to break compatibility if their old
implementation doesn't quite match.

it makes it impossible for IDEs to hint/autocomplete without
project-specific plugins

That's a good argument for standardisation, but doesn't require moving
out of the docblock; in fact, it doesn't even require any action from
this list, as PHP-FIG could simply agree a PSR, and IDEs like PHPStorm
would use that as an implementation guide.

and adds this odd notion that removing some comment blocks might break
an app (which is just awful).

If it helps, just think of /** ... */ as not being a comment, but
already a first-class piece of syntax. Note that the parser already
thinks so - hence we can have functions like
ReflectionMethod::getDocComment. IDEs also parse docblocks already, and
most syntax highlighting editors can probably style them differently
from comments so that you don't delete them by mistake.

Now, if annotations were being implemented as something brand new to
PHP, like say Traits were, I'd agree that we should look to languages
like Java and C# for syntax ideas. But since a lot of people have
already invented annotations using docblocks, and since docblocks are
already supported by the reflection classes, I'm not convinced of why we
shouldn't just carry on down that route.

Regards,

Rowan Collins
[IMSoP]

9 years ago by Lester Caine — view source

unread

Now, if annotations were being implemented as something brand new to
PHP, like say Traits were, I'd agree that we should look to languages
like Java and C# for syntax ideas. But since a lot of people have
already invented annotations using docblocks, and since docblocks are
already supported by the reflection classes, I'm not convinced of why we
shouldn't just carry on down that route.

Thanks Rowan ... that just about sums it up better than I did ...

Native Annotation Syntax

-- Lester Caine - G8HFL

Regards,

Regards,

Regards,

Regards,

Regards,

Regards,

Regards,

Regards,

Regards,

Regards,

Regards,

Regards,

Regards,

Regards,

Regards,

-- Lester Caine - G8HFL

Regards,

--
Lester Caine - G8HFL

--
Lester Caine - G8HFL