PHPDocumentor. Can I add link to property from it's getter description?

Question

/**
* @property $Property
*/
class SomeClass {

    public function __get($name){
       return $this->{'get'.$name};
    }

    /**
     * Some description
     * @return bool
     */
    public function getProperty(){
       return true;
    }

}

So the question is - how can I see description from getProperty() by viewing documentation of $Property? Or just see link to getProperty() documentation...

Answer 1

The question seems to be the reverse of the title. Do you want to look at the property and see the getter's description, or do you want to look at the getter and see the property's description?

I'll assume you want both. However, you can't actually get either. At most, one's description could contain a link to the other, but not actually contain the other's description in its own description.

Here, the property's description will contain a link to the getter's doc.

/**
 * @property $Property is controlled by {@link getProperty()}.
 */
class SomeClass {

    public function __get($name){
       return $this->{'get'.$name};
    }

    /**
     * Gets the value of {@link $Property}.
     * @return bool
     */
    public function getProperty(){
       return true;
    }

}

There are two complications here: with regard to how magic things appear in the actual docs (and how IDEs display them); and with whether or not the {@link} inline tags actually do anything.

In phpDocumentor 1.x, magic stuff only appears as extra information listed on the class itself. In phpDocumentor 2.x, both magic properties and magic methods will appear as if they were true properties and methods. The 2.x behavior is a strong improvement. For IDEs, and I can only speak for Eclipse PDT, I see that it matches the 1.x behavior.

In phpDocumentor 1.x, the inline {@link} tag does function, and normally becomes a hyperlink to the document for the element (property, method) that it points to. However, since 1.x does not actually create a dedicated doc for magic things identified by @property and @method, then "{@link $Property}" cannot actually point to anything. It's possible that the text in the class docblock where the "@property $Property" description is shown might correctly show a link to getProperty(), but only because getProperty() is a true method, and as such it has its own doc. Had getProperty() been a magic method denoted by "@method getProperty()", then "{@link getProperty()}" would not have anywhere to point to.

In phpDocumentor 2.x, the inline {@link} tag is not implemented, and therefore it will end up just a visible text as if it had no tag purpose. Once 2.x implements this inline tag, then my solution above should be able to solve both of your potential questions.

Answer 2

I think the best you can manage is

@property $Property
@see getProperty

Answer 3

Use a class-level PHPDoc comment

/**
 * @method string getMyFirstProperty()  Return value of the property called first
 * @method float  getMySecondProperty() Return value of the property called second
 */

And yes, magic getters will appear in the IDE, which is really what makes it useful