As PHP keeps added language features one of the things we have to do is figure out how to document them.
Lately I’ve been hearing requests for a way to document virtual properties and methods on classes that are implemented using __call etc.
After talking a bit with Greg, I’m leaning towards adding in some new docblock tags to classes to allow these methods/properties to be documented.
It might look something like this:
<?php
/**
* whatever
*
* @property int $blah this is the short desc (no long desc allowed)
* @property-read int $foo read-only variable
* @property-write string $oof write-only variable
* @method int myfunc(int $var, string $param2, Object $param3 = null) description of myfunc
*/
class magicClass {
}
?>
My big concern with this approach is it can lead to a unwieldly class level docblock and it makes it hard to add large descriptions. On the plus side this is easy to implement and normally when you have a virtual method/property it doesn’t need a lot of description.
Finally if anyone has thoughts on managing changes like this in the future let me know. Right now we consider the phpDocumentor manual to be the official guide to how things work, but im not sure if that works that well for other people writing phpdoc parsers (ide’s etc).
Related Bugs:
