Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:92931
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>
 <CAFp73XtqBtLdoTykrg_1eeJZTFszcmutNpynmyGKEizPiC2Juw@mail.gmail.com>
 <571DCA6A.2070803@zend.com>
 <CAFp73XsVJ=1QxvwLbqvDw8o3BD6Ly7BjrP5X+68O=z6iH-brWA@mail.gmail.com>
 <571E35D8.8080504@zend.com> <571E4A83.3080304@garfieldtech.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>
Message-ID: <79c9df57-ee45-f415-3172-95f8229bbece@gmail.com>
Date: Fri, 29 Apr 2016 13:36:06 +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: <57234D3D.1070602@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)

Lester Caine wrote on 29/04/2016 13:02:
> In my book this is DIRECTLY relevant to the current discussion!
>
> We have been adding attributes via docBloc annotation since PHP4 days.
> This has partly been accepted as the default way of doing it and phpDoc
> was originally part of the PEAR support structure. A large section of
> legacy code has well written phpDoc annotation and simply adding the
> current requested attributes to that platform creates no work in the
> core code.

I think there is a misunderstanding here about what code 
attributes/annotations are for, and it's understandable given current 
practises.

For instance, you might see a block that looks like this:

/**
  * This is a very cool method.
  * @param string $input A stringy thing
  * @return boolean Success
  * @Magic(42)
  */
public function foo($input)

Here we have two tags for generating documentation (@param and @return) 
and one intended to be accessed via Reflection and add some special 
behaviour (@Magic(42)). It is only the behavioural tag that we are 
discussing when we talk about "attributes/annotations".


In Java, the same block would be in two different parts:

/**
  * This is a very cool method.
  * @param input A stringy thing
  * @return Success
  */
@Magic(42)
public boolean foo(string input)

Or in C#:

/// <summary>
/// This is a very cool method.</summary>
/// <param name="input">A stringy thing</param>
/// <returns>Success</returns>
[Magic(42)]
public boolean foo(string input)


Note that the "Magic(42)" uses different syntax, built into the 
language, while the documentation parameters stay in comment syntax, and 
are mostly just a convention followed by documentation tools. This is 
what is being proposed for PHP:

/**
  * This is a very cool method.
  * @param string $input A stringy thing
  * @return boolean Success
  */
<<Magic(42)>>
public function foo($input)


Thus the behaviour of docblocks is not going to change, and reading 
their content remains the responsibility of whatever tool you use to 
generate documentation from them. The core code has no responsibility 
for defining them, and cannot force the developers of documentation 
generators to treat them in any particular way.

Regards,
-- 
Rowan Collins
[IMSoP]