phpDoc-无参数或返回值

Question

假设我有以下类存根：

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;
    }
}

beCourteous()方法实际上不接受任何输入，也不产生任何返回值。什么是正确的phpDoc块？

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;
}

Answer 1

一个不接受参数也不返回值的函数在文档注释中不应该有@param或@return。但是，您可以（也应该）包含描述

/**
 * Echos a salutation to <code>$this->guestsName</code>
 */
public function beCourteous() {
    echo 'Salutations, dear ' . $this->guestsName;
}

请参阅此处：（相关，不完全是重复）PHPDoc:@是否需要返回void？

这里：http://en.wikipedia.org/wiki/PHPDoc

Answer 2

您选择的phpDoc将在每种情况下识别一个函数。但是，也许您希望返回字符串并在类之外构建响应字符串。