phpDoc - 无参数或返回值答案

【问题标题】：phpDoc - no parameters or return valuephpDoc - 无参数或返回值
【发布时间】：2014-12-19 10:16:22
【问题描述】：

假设我有以下类存根：

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

【问题讨论】：

标签： php phpdoc docblocks

【解决方案1】：

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

【讨论】：

返回字符串并不总是有效。例如，我有一个输出大文件内容的脚本。我没有意识到该文件会变得有多大，并且当我从函数返回它时，它会导致脚本内存不足。改用 readfile ，它不会使用任何接近尽可能多的内存。

【解决方案2】：

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

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

见这里：（相关，不完全是骗子） PHPDoc: @return void necessary?

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

【讨论】：

这是真的，我在 OP 中忘记提及了。假设在这种情况下我不包括描述；文档块的内容将为空。正常的处理方法是什么？
明确显示@return void 告诉您的用户“不期望返回值，因此不要假设任何值”。根本没有返回标签告诉您的用户“假设没有给出返回值”。归根结底，它在功能上都是一样的……这真的取决于你喜欢对你的读者有多明确。我总是在我的中包含@return void，因为我不喜欢假设 ;-)
引用wiki @return|这个标签不应该用于定义为void返回类型的构造函数或方法。