Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:64707
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain gmail.com designates 209.85.214.173 as permitted sender)
MIME-Version: 1.0
In-Reply-To: <CAOhuFvZv9ePXkW+6ZDi_w+-Y-PHBLXSXAMdupX0vst8rsQ+L1g@mail.gmail.com>
References: <CADqTB_h4eh4mPi89uRps6vZWXjDEhUtcBopL7jmO-UgRuyf19w@mail.gmail.com>
 <50EBDEEE.8070605@sugarcrm.com> <CAOfKkdQXh53oxpCQ59R_hcws4Pd=q+O_VMOZ=tS+F2_7qof3RA@mail.gmail.com>
 <50EC6569.6030202@sugarcrm.com> <CAEZPtU5gGsr97ZD+ybxgnRj7=X2mtL4+m0qWdYMg1qsgj0+MrA@mail.gmail.com>
 <50EC917C.3070805@sugarcrm.com> <CAOhuFvZv9ePXkW+6ZDi_w+-Y-PHBLXSXAMdupX0vst8rsQ+L1g@mail.gmail.com>
Date: Wed, 9 Jan 2013 00:42:36 +0200
Message-ID: <CANVTSm6DOWZvP34ETWWHDu_437PFc2OKGfNtyncTu9S3Y_EccQ@mail.gmail.com>
To: Rafael Dohms <listas@rafaeldohms.com.br>
Cc: Stas Malyshev <smalyshev@sugarcrm.com>, Pierre Joye <pierre.php@gmail.com>, 
	Pierrick Charron <pierrick@webstart.fr>, "internals@lists.php.net" <internals@lists.php.net>
Content-Type: multipart/alternative; boundary=14dae93998ebc395b904d2ceaab9
Subject: Re: [PHP-DEV] [RFC] Reflection annotations reader
From: g.b.yahav@gmail.com (Yahav Gindi Bar)

--14dae93998ebc395b904d2ceaab9
Content-Type: text/plain; charset=ISO-8859-1

> If I read this thread correctly then almost everyone agrees that PHPUnit,
> Symfony, ZF, Doctrine, etc, all use annotations in the DocBlock because
> there
> is no available alternative that enables them to use annotations.
>

Yes, I understood that too.


As far as I am concerned I'd separate this topic into a DocBlock parser
(that
might take into account the current state of affairs with DocBlock
Annotations)
and actual Annotation support.

I agree.


I disagree with the above, documentation generators are _unable_ to use the
> Reflection library of PHP due to issues with Dynamic Reflection and the
> processing of a large amount of files (report on request) with it.
>
> To phpDocumentor and related projects it would be imperative that a
> DocBlock parser is available without having to use the Reflection
> extension.
>

Even so, I think that a pointer to that function should be present in the
Reflection, so even if we got SPL parser, one could access it using
Reflection since it's the obvious way he/she would look for that.




On Tue, Jan 8, 2013 at 11:51 PM, Rafael Dohms <listas@rafaeldohms.com.br>wrote:

> On Tue, Jan 8, 2013 at 10:37 PM, Stas Malyshev <smalyshev@sugarcrm.com
> >wrote:
>
> > Hi!
> >
> > > Everyone I talked to who implemented annotations in docblocks did it
> > > as hack because there is no native support. This is not something that
> > > belongs to docblocks. It would be nice if you could take a look at the
> > > c# doc, there are really good concepts there.
> >
> > I know why they did it, and we already discussed that stuff in the last
> > annotation discussion. What I mean here is that presenting it as if the
> > notion of meaningful comments is completely unheard of in PHP and nobody
> > expects it is just wrong. Maybe it was so years ago, but it is
> > definitely not true now - de-facto meaningful comments *are* the
> > standard now, and have a lot of use, and nobody with any experience is
> > surprised by them. Regardless of *why* is it so, it is a fact.
> >
> > Stas,
>
> That still does not make it the right place. Annotations went into
> docblocks
> because it was the only place reflection could provide the needed
> information at
> runtime. Just because we now treat docblocks as 1st class citizens does not
> mean annotations should be there.
>
> Does that mean that annotations should be in docblocks and not in core
> for the reason of "we all know docblocks exist". I would seriously expect
> at the very least a stronger reason. These were some of the ones i heard
> before:
>
> 1. The syntax is crap: this is solvable, let's find the right syntax
> 2. PHP does not need it: i think we have proven the use already, every
> major FW has a
> implementation of this, there is clearly demand.
>
> So if we are going to get anywhere with this discussion I suggest getting
> back to
> the original RFC and working on solving the issues instead of discussing
> developer folklore.
>
> --
> Rafael Dohms
> PHP Evangelist and Community Leader
> http://doh.ms
> http://wwwamsterdamphp.nl
>

I, too, think that we should re-consider using Annotation. This feature
proved itself as usable
My opinion is that we should separate this discussion into two fields which
will get their own RFC:
- We should recreate / reconsider the Annotation feature. It proved itself
as something that developers wish to get, and they mix between abilities
(the ability to write documentation in userland) just to achieve that
because we didn't provided that.
- A doc-block parser (in SPL, core or whatever) that can analyze the
doc-comment and separate it. I think that we should still implement this
even if we'll have Annotation because this is a usable feature in PHP that
can give information for writing API's and such. However, in case
Annotations will be implemented - I understand that you may say that my
argument is weak.

--14dae93998ebc395b904d2ceaab9--