Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:92932
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: error (pb1.pair.com: domain beberlei.de from 74.125.82.52 cause and error)
MIME-Version: 1.0
In-Reply-To: <79c9df57-ee45-f415-3172-95f8229bbece@gmail.com>
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>
	<79c9df57-ee45-f415-3172-95f8229bbece@gmail.com>
Date: Fri, 29 Apr 2016 14:49:34 +0200
Message-ID: <CAEPJdunLsPfnE5ebZkcARRO_RR9ni1jWQJg_FW_9XZm9XhpPsQ@mail.gmail.com>
To: Rowan Collins <rowan.collins@gmail.com>
Cc: PHP Internals <internals@lists.php.net>
Content-Type: multipart/alternative; boundary=001a114700fa22eba305319f13f8
Subject: Re: [PHP-DEV] PHP Attributes -> docBloc alternatives ...
From: kontakt@beberlei.de (Benjamin Eberlei)

--001a114700fa22eba305319f13f8
Content-Type: text/plain; charset=UTF-8

On Fri, Apr 29, 2016 at 2:36 PM, Rowan Collins <rowan.collins@gmail.com>
wrote:

> 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.


This.

Lester, nobody wants to move phpdoc out of the *doc* comment. Its still
documentation. It will stay,.

We want to move the "annotations" out of the docblocks that are evaluated
at runtime for configuration. Thats two different things. That is what the
attributes RFC is for.

>
>
> Regards,
> --
> Rowan Collins
> [IMSoP]
>
> --
> PHP Internals - PHP Runtime Development Mailing List
> To unsubscribe, visit: http://www.php.net/unsub.php
>
>

--001a114700fa22eba305319f13f8--