Hi internals, Just like before, people are confusing documentation support with behavioral support. No matter what people say, documentation is documentation and code still behaves the same with and without the comment docblock. When talking about behavioral marks, removing that piece makes your code crash.
While creating Doctrine Common Annotations, I was forced to add them in the docblock because there was no way in the language to not place it there. This is not an excuse to tell everyone now that only because different tools used docblocks (because of the lack of support), this is now the standard. It is a hack using the documentation support to add behavioral support, point made. Of course it does not invalidate the documentation. Docblocks should still have a way to be parsed, but that information is static. I really pushed hard annotations in the past, mainly because I was foreseeing that many tools would start adopting behavioral support. Behaviors can be declared by other ways, like XML, YAML or even PHP. But the fact of bringing things together under different perspectives (read as aspects) turns a certain piece of code more powerful and informative than ever. I wanted to use the term aspects on purpose because that is another subject that people normally bring in about highly coupled classes. This is conceptually wrong because if I only want to populate class properties, I don't even touch other aspects like validation and filtering, so there's no coupling, since code is used/dependent elsewhere. Another point that got mentioned in the past was the lack of standardization of annotations, which would lead different projects a good portion of time to refactor to accommodate possible new support. Currently, the status is quite different from 2010. Now, except phpunit, almost all major projects are pointing to Doctrine Common Annotations. Some examples are Doctrine itself, Symfony, Zend Framework, Drupal, PPI, Flow3 and many others that I can bring here. It does seem to me that language requires this functionality like 2 years ago, and everyone is paying the price by using a hacked solution that now people claim it's the standard. No, it's not the standard and it will never be. What happened is that annotations indeed became a standard in PHP using a hack due to the lack of support in core and it seems more and more we delay the inclusion it will get worse to remove this hack because of this "standardization". I wonder if that was the idea back in 2010, or maybe if it was due to the lack of knowledge, interest or willingness. For those still wondering how it could be applied, here are some links: http://drupal.org/node/1882526 http://docs.doctrine-project.org/projects/doctrine-common/en/latest/reference/annotations.html https://packages.zendframework.com/docs/latest/manual/en/modules/zend.form.quick-start.html#using-annotations http://symfony.com/doc/master/book/validation.html I think we should split this discussion to 2 points. One that details Annotations support for the language and a second one, as a PECL extension that add Docblock parsong support. For Annotations, I recommend that you guys that a look at RFC I created back in 2010: https://wiki.php.net/rfc/annotations The docblock one (https://wiki.php.net/rfc/annotations-in-docblock) was abandoned because I faced different problems that couldn't fix without requiring a more powerful solution. So, do you guys wanna discuss again this possible inclusion? On Tue, Jan 8, 2013 at 5:42 PM, Yahav Gindi Bar <g.b.ya...@gmail.com> wrote: > > 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 <lis...@rafaeldohms.com.br > >wrote: > > > On Tue, Jan 8, 2013 at 10:37 PM, Stas Malyshev <smalys...@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. > -- Guilherme Blanco MSN: guilhermebla...@hotmail.com GTalk: guilhermeblanco Toronto - ON/Canada
