Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:89414
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain gmail.com designates 74.125.82.42 as permitted sender)
References: <CAJGzsHriGp9PoYq++=CBQptFYZQiAsa+yxxN076BHxMQGD6HrA@mail.gmail.com>
 <5654B516.4020700@gmail.com>
 <CAESVnVpe3+9=N5rkcHp2O5cdGuFnt_EQ=sSV8ucpv5w=ox-NaA@mail.gmail.com>
 <CAJGzsHoP5mc2_demfWM3r7exN4qLThANcbcwo9SBydGpvmB1WQ@mail.gmail.com>
To: PHP internals <internals@lists.php.net>
Message-ID: <5655E790.9060408@gmail.com>
Date: Wed, 25 Nov 2015 16:53:36 +0000
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:38.0) Gecko/20100101
 Thunderbird/38.3.0
MIME-Version: 1.0
In-Reply-To: <CAJGzsHoP5mc2_demfWM3r7exN4qLThANcbcwo9SBydGpvmB1WQ@mail.gmail.com>
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 7bit
Subject: Re: [PHP-DEV] Native Annotation Syntax
From: rowan.collins@gmail.com (Rowan Collins)

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]