文档错误标签[关闭]

Question

我在触发错误的类中有一个方法。

/**
 * Get info
 * @return string|FALSE Info
 */
public function getInfo()
{
    if ($this->info) {
        return $this->info;
    }

    trigger_error('Missing info', E_USER_WARNING);
    return FALSE;
}

我不想在这里抛出异常，因为我真的希望/需要这段代码继续运行。在其他地方，我记录了这个错误，记录错误超出了这个类的范围。

但是我该如何记录呢？对于一个例外，我会使用：

/**
 * @throws Exception
 */

错误有类似的东西吗？我真的希望其他开发人员能够轻松了解我的代码中发生了什么。

Answer 1

没有用于错误的 phpdoc 标记。

trigger_error() 返回布尔值，因此您的方法不会返回或抛出任何东西。除非您的错误处理程序阻止，否则执行将继续执行，因此使用 @return 或 @throws 会误用它们，并且可能会使阅读您代码的任何人感到困惑。

---

我会使用不同的方法。

我会这样做：

/**
 * Has info
 *
 * @return bool Whether info is available
 */
public function hasInfo()
{
    return (bool) $this->info; // or use isset() or whatever you need
}

/**
 * Get info
 *
 * @throws Exception
 * @return string The info string
 */
public function getInfo()
{
    if (! $this->hasInfo()) {
        throw new Exception('Missing info');
    }

    return $this->info;
}

然后从您的其他代码中，您可以：

if ($object->hasInfo()) {
    $info = $object->getInfo();
} else {
    // no info!
}

我还会在我的代码库的根目录中捕获异常：

try {
    MyApp::run();
}
catch(Exception $e) {
    // handle error, eg. display fatal error message
}

Answer 2

我同意其他人的观点，即我会在这里改变我的编码方法，但要解决你的直接问题——我可能会使用@internal 标签来解释你希望开发人员注意的事情的。当然，当您针对此代码运行 phpDocumentor 时，@internal 标记不会出现在您生成的文档中，除非您使用 --parse-private 运行时选项...这是因为 internal-info-for-devs 被假定为关闭限制消费者/对 API 感兴趣的读者，就像“@access private”项目一样。