There and Back Again

phpDocumentor enhancements

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:

8 thoughts on “phpDocumentor enhancements

  1. Toby

    Hi!

    Personally I like this approach quite much, maybe because it looks quite similar ;) to the approach we discussed at work for documenting our properties.

    Anyway, while reading your blog post it came to my mind, that one could simply move the property docs, where they belong, to avoid poluting the class-level docblocks: To the __get/__set/__call method. This would mean that you would have to document read/write properties twice, which could by worked around by simply adding the tags for the properties, but only documenting their description once. See this example

  2. Joshua Eichorn Post author

    Moving the docs down to the magic methods is an interesting approach. I think it makes the implmentation a bit harder but it should be worth it.

    Also wordpress ate your example url.

  3. Pingback: PHPDeveloper.org

  4. Pingback: Sooey » Blog Archive » phpDocumentorに仮想プロパティ用の新記法?

  5. Derick

    Actually Toby, that is something we wouldn’t want. Properties are part of the *class* and not of the __set() and __get() methods. By separating them out (you need to document some of them twice as well) it’s going to be less maintainable.

  6. aric caley

    My solution to this is to define the property or method, but then unset them in the constructor so that __call/__get/__set can handle them.