Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:92974
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain gmail.com designates 209.85.218.50 as permitted sender)
MIME-Version: 1.0
In-Reply-To: <57247266.9050609@lsces.co.uk>
References: <BY2PR0201MB178479B3AF8BD49583233034BF6E0@BY2PR0201MB1784.namprd02.prod.outlook.com>
	<5719CDB2.90103@zend.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>
	<CAEZPtU6DUpvh3SF2c8kisMaZ_sm4Lc_eRuh-a_S92SVKg6Ok_Q@mail.gmail.com>
	<57247266.9050609@lsces.co.uk>
Date: Sat, 30 Apr 2016 16:00:45 +0700
Message-ID: <CAEZPtU6tk=s3wCuwfZ1XVC=0iXmObZFnzNpu6LPmwG2opwHpKw@mail.gmail.com>
To: Lester Caine <lester@lsces.co.uk>
Cc: PHP internals <internals@lists.php.net>
Content-Type: text/plain; charset=UTF-8
Subject: Re: [PHP-DEV] PHP Attributes -> docBloc alternatives ...
From: pierre.php@gmail.com (Pierre Joye)

On Sat, Apr 30, 2016 at 3:52 PM, Lester Caine <lester@lsces.co.uk> wrote:
> On 30/04/16 09:38, Pierre Joye wrote:
>>> Sorry if you didn't spend the last 6+ years of your free time
>>> > <
>> https://github.com/phpDocumentor/phpDocumentor2/commit/66dc9069085dcea957508f84e9c79eaf4c234586
>>> >
>>> > (yes, that is an import) maintaining an open-source project focused on
>>> > annotations-based documentation.
>
>> This is not what it does (or I hope it does not). And it makes me sigh to
>> read such descriptions. Annotations or attributes are not documentations.
>> For the record for this thread :)
>
> It was the use of the 'standard' defined by phpDocumentor2 to 'define'
> php-annotations that trigger my current noise, but while I agree with
> you, the information contained in what ever method is used to add
> 'attributes' to the 'annotations' also forms a useful part of any
> documentation. In my book the two go hand in hand. Which is why I
> changed the title of the thread.

Annotations/Attributes define new behaviors or properties and is used
by whatever will process the annotations/attributes. Indeed they
provide a bit more information for the user but this is a side-effect,
not a goal.

Documentations (docblock fe) is used to generate documentation or is
used as inlined doc, by human for human.

I understand (that) users can see as similar or same but it is
critical to keep in mind that they are not, at all. That would help to
design and implement what we need for attributes or annotations
support.

Cheers,
-- 
Pierre

@pierrejoye | http://www.libgd.org