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 <z...@zend.com> wrote: > At 20:24 11/09/2010, Pierre Joye wrote: >>On Sat, Sep 11, 2010 at 8:19 PM, Stas Malyshev <smalys...@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 -- PHP Internals - PHP Runtime Development Mailing List To unsubscribe, visit: http://www.php.net/unsub.php
