phpDoc-无参数或返回值

假设我有以下类存根：

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

---

您选择的phpDoc将在每种情况下识别一个函数。

---

但是，您可能希望返回字符串并在类之外构建响应字符串。

不接受参数也不返回值的函数不应在文档注释中包含

@param

或

@return

。但是，您仍然可以（并且应该）包含一个描述

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

看这里：（相关的，不完全是一个傻瓜）

在这里：

---

这是真的，我在OP中忘了提到一些东西。在这个例子中，我没有包括描述；docblock的内容将为空。通常的处理方法是什么？显式显示

@return void

告诉用户“不要期望返回值，所以不要对返回值进行任何假设”。完全没有返回标记会告诉用户“假设没有给出返回值”。在一天结束的时候，它的功能都是一样的。。。这真的取决于你喜欢对你的读者有多明确。我总是将

@return void

包含在我的文档中，因为我不喜欢假设；-）引用wiki@return |此标记不应用于使用void返回类型定义的构造函数或方法。返回字符串并不总是有效的。例如，我有一个脚本，可以输出一个大文件的内容。我不知道该文件会有多大，当我从函数返回脚本时，它会导致脚本内存不足。改为使用readfile，因为它不会占用太多内存。