Say I have the following class stub:
class Gentleman {
/** @var string */
protected $guestsName;
/**
* @param string $name The name of our esteemed guest
*/
public function __construct($name) {
$this->guestsName = $name;
}
public function beCourteous() {
echo 'Salutations, dear ' . $this->guestsName;
}
}
The beCourteous()
method doesn't actually take any input, or produce any return values. What is the correct phpDoc block?
public function beCourteous() {
// No docblock
echo 'Salutations, dear ' . $this->guestsName;
}
/**
*
*/
public function beCourteous() {
// One blank line
echo 'Salutations, dear ' . $this->guestsName;
}
/**
*/
public function beCourteous() {
// No blank lines
echo 'Salutations, dear ' . $this->guestsName;
}
A function which accepts no parameters nor returns a value should not have @param
or @return
in the doc comment. However, you can (and should) still include a description
/**
* Echos a salutation to <code>$this->guestsName</code>
*/
public function beCourteous() {
echo 'Salutations, dear ' . $this->guestsName;
}
See here: (Related, not exactly a dupe) PHPDoc: @return void necessary?
And here: http://en.wikipedia.org/wiki/PHPDoc