Re: Re: PHP Annotations RFC + Patch

Hi Benjamin, I agree with you 100 percent. Greetings, Christian On Mon, 13 Sep 2010 17:38:37 +0200, Benjamin Eberlei <kontakt@beberlei.de> wrote: > I strongly disagree! > > PHPDocs are for what their name suggests, for comments, not for runtime > code information. They allow arbitrary characters, their intent is for > human-readible documentation only. > > Yet they are used for service description (Zend_Soap_Autodiscover, > Zend_XmlRpc), metadata mapping or phpunits "annotations", just because > there is nothing better suited. > > Primary difference of Annotations, they are not only human- but also > enforced to be machine-readable. Annotations are runtime configuration or > metadata, throwing compile time parse errors when not followed correctly. > That has nothing to do with documentation, it is an very elegant way to > extend classes, methods and properties with metadata information, > configuration and code right next to each other. > > The primary target for annotations are framework and library integrations: > validation, forms, metadata mapping, static mvc configuration such as > routing, view selection or acls. Why do these features not exist with > current php libraries yet? Because developers see php doc blocks for what > they are: Comments! > > With Doctrine2 and Symfony2 we see some early experiments with annotations > in PHP Docs, but they only highlight the drawbacks: > > 1. Developers should expect to be able to delete a comment/docblock > without altering the code-path. > 2. Errors in the Doc-Blocks "expected formatting" are left for the > userland developer to detect. IDEs or the PHP Parser simply don't care. > 3. There is no real difference for a human only readable doclbock starting > with /** or /*, however PHP just doesnt publish the /* docblocks to the > userland, leading to countless errors when that single star is missing. > 4. every IDE or code-highlighting prints them in light grey, making them > sort of invisible. > > That is why annotations are needed, they make metadata a language level > construct, not a hack that is possible, because Reflection allows us to > access the comments of methods, functions, classes, ... > > greetings, > Benjamin > > On Mon, 13 Sep 2010 15:05:57 +0200, Zeev Suraski <zeev@zend.com> wrote: >> At 20:24 11/09/2010, Pierre Joye wrote: >>>On Sat, Sep 11, 2010 at 8:19 PM, Stas Malyshev <smalyshev@sugarcrm.com> >>>wrote: >>> > Hi! >>> > >>> >> The separator never was a problem... but I definately don't want to >>> >> see another 6 months just to define what would the separator be. >>> >> If we need to drop [] in favor of array support, I vote for ! as >>> >> separator. >>> > >>> > The separator is not a problem (even though 1-char one produces much >>> > less >>> > clutter). The cryptic syntax is. >>> >>>It seems that there is a misunderstanding about the goals of the >>>annotations. They are not meant to be read by human being >>>(javadoc/phpdoc/etc. are) but to be parsed automatically to be used >>>for services. >>> >>>In that sense, to have a syntax closed to one of the best (or less >>>worst, if you are on the opposed side ;-) syntax out there (c#/.net) >>>may be a good thing to do, instead of re einventing the php wheel. >> >> I'm not sure we've seen a good reason to add annotations instead of >> using PHPDoc. Sure, PHPDoc isn't a perfect fit for certain purposes, >> but I think it certainly falls in the good-enough fit for most >> purposes. It's also both machine and human readable, and best of all >> - it's already there. >> There should be overwhelmingly strong reasons to add a whole new >> branch of syntax to PHP, I for one don't see the huge gain >> annotations bring on top of PHPDoc. >> >> Zeev