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)
 {

 }

实际上这是我首选的方法，因为它明确描述了所有可能的类型。但我听到有人抱怨在文档中无法明确判断参数是否可选。

我知道有一个非官方惯例是加上“(optional)”来表示可选参数。

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

 }

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

一般来说，我甚至可以同时使用它们：

 * @param Type2|null $bar (optional)

但是在我看来，它并不好看。

你可以给我一些反馈意见，或者更好的是，给我一些相应的编码规范/样式指南的链接吗？

- Alex

---

如果您有一个意图成为类的类型，为什么要将其设置为null？可以使函数在开始时进行智能检查，或者创建一个带有不同参数的附加函数。 - Markus Zeller

这听起来更像是基于个人观点的事情。 - Nigel Ren

这不是关于修改代码。可选参数通常会出现问题。这是关于phpdoc标准的问题。一些人对此有非常强烈的观点，这也让我感到惊讶。 - Alex

Answer 1

@param Type2|null $bar

从phpDocumentor的角度来看，这是正确的方式......请参见此处展示的getOption()方法的最后三个参数。

- ashnazg

---

那么 Type2 $bar = 'Default' 呢？在这种情况下，@param Type2|null $bar 是错误的（根据phpstan）。 - kitingChris

如果您将可选参数默认设置为非空值，则“|null”部分将不会出现在类型字符串中。相反，标记将是“@param Type2|string $bar”。 - ashnazg

哦天啊。当然Type2不是一个字符串... Type2 $bar = Type2::getDefaultInstance() 更符合我的想法 :) - kitingChris

既然你不能像那样将函数调用放入原始函数的参数签名中，那么你可能确实希望在签名中有可选的 null，在函数体中进行 null 检查以触发 getDefaultInstance() 调用来填充它。因此，参数标记将与我的答案中一样，但是一些额外的注释可以强调隐式发生的调用（可以通过参数描述中的内联 {@link} 标记、单独的 @see 标记，甚至是使用内联 {@link} 的 @internal 标记来实现）。 - ashnazg

是的，其实我应该知道的。只是想举个例子来阐述我的观点。但我想我走错了方向。没关系 :D - kitingChris