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 <la...@garfieldtech.com>
wrote:
> On 11/25/15 11:48 AM, Rowan Collins wrote:
>
>> Larry Garfield wrote on 25/11/2015 17:39:
>>
>>> On 11/25/15 11:00 AM, Rowan Collins wrote:
>>>
>>>> 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
>
>
>
> --
> PHP Internals - PHP Runtime Development Mailing List
> To unsubscribe, visit: http://www.php.net/unsub.php
>
>
--
Guilherme Blanco
MSN: guilhermebla...@hotmail.com
GTalk: guilhermeblanco
Toronto - ON/Canada
