在用PHPDoc描述变量时，我对何时使用null作为类型感到困惑。类型提示是应该描述外部调用方预期和遵守的希望和期望，还是应该记录变量的所有可能类型，即使希望它在实践中是一种非常具体的类型？
示例1：默认值。以下函数只需要非null值。但是，如果没有传递任何值，它将默认为null，并显式检查该值，以确定是否传递了任何内容，并为这种情况返回一个特殊值。希望除了一个整数之外，没有任何外部调用程序会传递任何东西。null应该用在@param类型中，如下所示，还是应该只指定int，因为如果传递了任何内容，这就是我们想要传递的内容？
/**
* @param int|null $bar
*/
function foo($bar = null) {
if(is_null($bar)) {
return 'ABC';
}
return doSomething($bar);
}
示例2：实例属性。我们只希望$bar包含整数。也就是说，如果没有为bar设置任何内容，则该实例属性的默认PHP值为null。我需要在每个使用$bar的地方说明这一点吗，下面可能有一个null类型？
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;
}
}
基本上，我发现自己几乎把每一个@param和@var声明都和|null放在一起，因为从技术上讲，它可能就是那个值。但在实践中，它不应该是。我应该期望我的几乎所有类型都包含null的可能性，还是应该假设这一点，并且我应该避免指定它，除非我期望显式设置或接收null的值？
在实践中，我倾向于让param标记只列出您想要传递的。然而，对于返回标记，您确实需要列出所有可能返回的类型。这就是为什么我在这两者上存在分歧。
由于PHP不是强类型的，即使你说"只传入一个int"，你的方法仍然需要确保它没有被意外地传递。仅仅因为方法代码试图处理接收其他类型，你不希望你的文档告诉你的用户"当然，你可以给我一个NULL，我会帮你做点什么"。你想让你的医生说"给我一个int，句号"。
在考虑返回值时，您的用户真的非常需要知道您的方法可能返回的每一个潜在返回类型，因为他们真的需要在代码中覆盖他们的基础，以处理您的方法可以返回的所有类型。
是的，根据PHPDoc标准，您应该在所有地方都包含null(当然，如果适用的话)
请参见此处：http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.param.pkg.html
数据类型应该是有效的PHP类型(int、string、bool等)对象类型的类名，或者简称为"混合"。此外，您可以为单个参数列出多个数据类型，方法是用管道(例如"@param int|string$p1")。您可以记录参数列出的或将由标准PHP解析的任何可选参数函数func_num_args()/get_func_arg()。建议的名称格式与func_get_arg()一起列出的参数为：$paramname如果只有一个参数$paramname，。。。如果参数的数量是无限制的