Hi!
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.
Nothing prevents us from using phpdocs for non-human-reading purposes. Actually, there is quite a lot of code that already does it successfully. I don't see anything heretical in having phpdoc tag parser in reflection and using it for metadata purposes - after all, phpdoc currently IS being used as metadata and actually it was its intent from the start.
Primary difference of Annotations, they are not only human- but also enforced to be machine-readable. Annotations are runtime configuration or
phpdoc tags are enforced to be machine readable as well.
metadata, throwing compile time parse errors when not followed correctly.
There's no such thing as compile time in PHP. Practically everything in PHP is runtime. And as I see, people want validation logic in their annotations - which makes it even more runtime.
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.
What prevents you from using plain old way of adding information to classes? I understand that new syntax is much cooler than boring old one - but besides that?
1. Developers should expect to be able to delete a comment/docblock without altering the code-path.
It's circular argument. If phpdoc is used for metadata, they can't.
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.
How it's a bad thing? IDEs can do whatever they want, and PHP parser shouldn't be broken by metadata.
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.
If you miss single dollar, comma or = sign, there could be errors too. So?
4. every IDE or code-highlighting prints them in light grey, making them sort of invisible.
Fix your IDE. My IDE knows about what phpdoc tags are :) Some IDEs lagging behind is not an argument in language design. IDEs can be fixed.
-- Stanislav Malyshev, Software Architect SugarCRM: http://www.sugarcrm.com/ (408)454-6900 ext. 227 -- PHP Internals - PHP Runtime Development Mailing List To unsubscribe, visit: http://www.php.net/unsub.php
