Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:92939
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain gmail.com designates 74.125.82.41 as permitted sender)
To: internals@lists.php.net
References: <BY2PR0201MB178479B3AF8BD49583233034BF6E0@BY2PR0201MB1784.namprd02.prod.outlook.com>
 <571E64A2.2040505@gmail.com>
 <CADqTB_hH4=Rx2ZV_WSJuCPzbnA-ERyFUE8ZsCew2Z6p0+FHWsg@mail.gmail.com>
 <5720A6B4.4000307@lsces.co.uk>
 <CADyq6sKBV0n+xnVhRxsP5RDf0oRLMnNO-BM1VEudRgcK1s199A@mail.gmail.com>
 <CADyq6s+P5p-xdJ8CQaFo3Nrwe7ooyCLg1p=98E0kcSscBbSe8A@mail.gmail.com>
 <CADyq6sJp-krEpGgat7hWm2YpvtfwAfK1ya0as4Tv2qtCSeNgAw@mail.gmail.com>
 <5721B9DD.3050300@lsces.co.uk>
 <CADyq6s+nJoHkMmA+iupA0+7jwJskkdLTe=os=gZDt3dqaJxT7A@mail.gmail.com>
 <57231ADD.9040006@lsces.co.uk>
 <CADyq6s+uELdzWoMd0GBvby205Po_xEpxKoEBkSc_qbxsS3YeXQ@mail.gmail.com>
 <572326A3.7000809@lsces.co.uk>
 <cb7724e7-7436-3013-5a3a-f7df6c35ed86@gmail.com>
 <57234D3D.1070602@lsces.co.uk>
 <79c9df57-ee45-f415-3172-95f8229bbece@gmail.com>
 <CAEPJdunLsPfnE5ebZkcARRO_RR9ni1jWQJg_FW_9XZm9XhpPsQ@mail.gmail.com>
 <57235F20.5080707@lsces.co.uk>
 <43b9c67f-3ec7-bacc-2608-552abbd1a3fa@gmail.com>
 <57237B36.1070301@lsces.co.uk>
Message-ID: <0d71618b-2ffa-7273-f9b9-aeabc35f4211@gmail.com>
Date: Fri, 29 Apr 2016 16:42:30 +0100
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101
 Thunderbird/45.0
MIME-Version: 1.0
In-Reply-To: <57237B36.1070301@lsces.co.uk>
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 7bit
Subject: Re: [PHP-DEV] PHP Attributes -> docBloc alternatives ...
From: rowan.collins@gmail.com (Rowan Collins)

Hi Lester,


Lester Caine wrote on 29/04/2016 16:18:
> I think that is part of the problem here. IDE's are currently making
> quite good use of existing annotation text, but if they have to be
> switched to modes where some other option takes priority then once again
> all the code has to be reworked ... which is where I'm stuck at the moment.


To be absolutely 100% clear, the attributes / annotations being 
discussed are NOT for use in documentation, they are NOT for use by 
IDEs, they are for use AT RUNTIME, by libraries which want to 
programmatically access them INSIDE PHP ITSELF.

And if your code has no machine-readable annotations, I can virtually 
guarantee that you won't need to make a single change to your docblocks 
for your IDEs to carry on using them in exactly the way they're using 
them now. Of course,


> As with 'strict typing' we add different styles of working which in some
> longer term world may be an elegant solution but short term just creates
> an annoying different way of doing a bit of the job?

To an extent, I agree with this. Most modern programming language 
features are just sugar on top of more general functionality. But again, 
let's be clear: the functionality this is duplicating is not docblocks, 
it is executable code. So an imaginary attribute "<<test($a < 42>)>>" 
above a function might replace the code "if ( $a < 42 ) { throw new 
Exception; }" inside the function.

There is some merit to saying that annotations already de facto exist 
inside docblocks, but that discussion has been had many times, and there 
is a brief summary in the current RFC: 
https://wiki.php.net/rfc/attributes#criticism_and_alternative_approach 
The most compelling argument to me is that since these aren't 
standardised, a lot of incompatible syntax exists out there that the 
parser would have to cope with (or force people to rewrite).


> The comments go hand in hand with the validation so
> why not keep them together?

This is true of any code. If I write "if ( $foo < 42 )", I might put a 
comment next to it, but I wouldn't put the if statement in the comment. 
So it would be with attributes/annotations: you would write the code 
that means something to the engine, and then you would put a comment 
next to it.

/**
  * @test($a < 42) Must not reach The Answer
  */
function foo($a) { ... }

vs

function foo($a) {
if ( $a < 42 ) { throw new Exception; } // Must not reach The Answer
...
}

vs

<<test($a < 42)>> // Must not reach The Answer
function foo($a) { ... }


All of these examples have a mixture of code and comments, positioned 
next to each other, but nonetheless separate.

Regards,
-- 
Rowan Collins
[IMSoP]