Question

在使用PHPDoc描述变量时，我很困惑何时使用null作为类型。类型提示是否应该描述外部呼叫者预期和遵守的希望和期望，或者他们是否应该记录所有可能类型的变量，即使希望它在实践中是一种非常特殊的类型？

示例1：默认值。以下函数仅需要非空值。但是，如果没有传递任何值，则默认为null并明确检查该值，以确定是否传递了任何内容，并为该情况返回特殊值。希望没有外部调用者将传递除整数之外的任何内容。是null类型中@param应该使用int，还是只应指定/** * @param int|null $bar */ function foo($bar = null) { if(is_null($bar)) { return 'ABC'; } return doSomething($bar); }，因为如果传递了任何内容，那就是我们要传递的内容？

class Foo {
  /**
   * @var int|null
   */
  public $bar;

  /**
   * @param int|null $bar
   */
  public setBar( $bar) {
    $this->bar = $bar;
  }

  /**
   * @return int|null
   */
  public function getBar() {
    return $this->bar;
  }
}

示例2：实例属性。我们只想要$ bar来包含整数。也就是说，如果没有为bar设置任何内容，则此实例属性的默认PHP值为null。我是否需要考虑使用$ bar的每个地方，可能的空类型如下所示？

@param

基本上我发现自己几乎每个@var和|null声明与null一起乱扔垃圾，因为从技术上讲，它可能就是那个值。但实际上它不应该。我是否应该期望我的几乎所有类型都包含null或者应该假设的可能性，除非我希望明确设置或接收{{1}}值，否则我应该避免指定它？

Answer 1

在实践中，我倾向于让param标签仅列出你想要传入的内容。但是，对于返回标签，你确实需要列出可能返回的每种类型。这就是为什么我对这两者的看法不同。

由于PHP不是强类型的，即使你说“只传入一个int”，你的方法仍然需要确保它没有传递意外的东西。只是因为方法代码试图处理接收其他类型，你不希望你的文档告诉你的用户“确定，你可以传递给我一个NULL，我会为你做一些事情”。你希望你的文档说“给我一个int，句号”。

在考虑返回值时，您的用户确实需要知道可能从您的方法返回的每种潜在返回类型，因为他们确实需要在他们的代码中覆盖他们的基础来处理您的方法可能返回的所有类型。

Answer 2

是的，根据PHPDoc标准，你应该在任何地方都包含null（当然，如果适用的话）

见这里：http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.param.pkg.html

数据类型应该是有效的PHP类型（int，string，bool等），a 对象类型的类名，或简称为“混合”。而且，你可以列出单个参数的多个数据类型，方法是用它们分隔管道（例如“@param int | string $ p1”）。您可以记录参数列出的或任何可由标准PHP解析的可选参数函数func_num_args（）/ get_func_arg（）。推荐的名称格式使用func_get_arg（）列出的参数是：如果只有一个参数，则为$ paramname $ paramname，...如果参数数量不受限制

我什么时候应该在PHPDoc类型提示和docblocks中使用NULL？

2 个答案: