In phpdoc, define class properties in separate file

I highly recommend against trying to inject a subclass. If the framework instantiates the class you're extending directly, you'll need to find a way to get it to use your subclass instead.

NetBeans and PhpStorm (and probably many others) will combine elements from multiple definitions of the same class/interface. This allows you to add properties and methods to any existing class without modifying the original source.

/**
 * Framework controller base class.
 * Provides helpers via __call().
 */
class Framework_Controller { ... }

Now create a file in your code base that you never require containing the same class definition. Your IDE should still parse it and merge its elements with the class above:

if (false) { // Safety first!
    /**
     * ACME Co. controller base class.
     *
     * @method ACME_Model_User getUser Load user via authentication helper
     */
    class Framework_Controller { /* nothing to add */ }
}

You can try using an interface and declaring the methods normally instead of with @method. That is what we did with Zend_View since it's already an interface. I haven't tried mixing class with interface to see if PhpStorm likes it.

It depends mainly on IDE you are using. I think you should extend base class and add there some new methods/properties with phpdoc comments. Of course changing framework's files is no solution as you already mentioned

You could extend the original class, redefine the function, with new doc, and call the parent function. e.g.

class newClass extends originalClass
{
    /**
    * New PHPDoc
    */
    function functionName($a)
    {
        return parent::functionName($a);
    }
}

Try to use @see or inline @link directives.