PHPDoc 中可选的可空参数

Question

假设我们的方法带有可选的可空参数 (PHP 7.0)，如本例所示：

/**
 * @param Type1 $foo 
 * @param Type2 $bar
 */
 function myFunction(Type1 $foo, Type2 $bar = null)
 {

 }

不幸的是，PHPDoc 文档中并不清楚，将第二个参数标记为可选和可为空的正确方法是什么。

通常我使用 "Type2|null" 表示法：

/**
 * @param Type1 $foo 
 * @param Type2|null $bar
 */
 function myFunction(Type1 $foo, Type2 $bar = null)
 {

 }

实际上这是我更喜欢的方式，因为它明确描述了所有可能的类型。但是我听到文档中关于参数是否可选的投诉并不明显。

我知道，类似接缝的非官方约定“（可选）”

/**
 * @param Type1 $foo 
 * @param Type2 $bar (optional)
 */
 function myFunction(Type1 $foo, Type2 $bar = null)
 {

 }

我不喜欢这种方法，因为从技术上讲，您可以明确提供 NULL 作为第二个参数。而且从 phpdoc 中还不清楚。

一般来说，我什至可以一起使用：

 * @param Type2|null $bar (optional)

但这看起来不太好，恕我直言。

你能给我一些反馈，或者更好的是，提供一些指向相应编码标准/风格指南的链接吗？

Answer 1

@param Type2|null $bar

是正确的方法，从 phpDocumentor 的角度来看...参见 getOption() 方法的最后三个参数，如图 here.

Optional nullable parameters in PHPDoc