How to mention a property in PHPDoc?

Question

I am trying to mention a property of my class somewhere else in other comments of my class, ie. in a method of that class.

For example if we have this code:

(please search for: property $mention -- @property Village::mention does not work)

class Village {
    /**
     * @var array Data container.
     */
    public $data = [];

    /**
      *
      */
    public $mention = 'Me';

    /**
     * Village constructor which injects data.
     *
     * @param $data
     */
    public function __construct($data) {
        $this->data = $data;
    }

    /**
     * A factory for our Villages.
     * 
     * @return Village
     */
    public static function hillbilly() {
        return new Village;
    }

    /**
     * Name tells the story...
     *
     * Now somewhere at this exact point I want to mention the
     * $mention property -- @property Village::mention does not work
     * nor does @property $mention either...
     *
     * @return array Rednecks unset.
     */
    public function redneck() {
        if(sizeof($data)) {
            unset($data);
        }

        return $data;
    }
}

$countryside = [
    'important' => 'data',
    'axe' => 'knifes',
    'shovel' => 'hoe',
    'trowel' => 'mixer',
];

$village = Village::hillbilly($countryside);

How do I make a mention of a property in PHPDoc?

Answer 1

If you need to have the $mention in the docblock text, one would usually use the inline see {@see element description}:

/**
 * Name tells the story...
 *
 * Now somewhere at this exact point I want to mention the
 * {@see Village::$mention} property.
 *
 * @return array Rednecks unset.
 * @see Village::$mention
 * @uses Village::$mention
 */
public function redneck() {
    if(sizeof($data)) {
        unset($data);
    }

    return $data;
}

The @see or @uses standalone tags are also available, but not for embedding the link into the docblock narrative text.

Note that older phpDocumentor only allowed the inlink link tag {@link url|element description}.