如何记录一个包含子数组（混合类型）的数组？

Question

为了记录一个可以接收字符串值的向量数组的变量:

/*
 * @var string[] An array of string objects.
 */
$foo = array('A', 'B', 'C');

为了记录一个变量，该变量可以接受一个数组，并接收其值为整数的向量：

/*
 * @var int[] An array of string objects.
 */
$foo = array(1, 5, 0);

如何记录值为混合数组的变量？

我需要记录像这样的一个数组：

$foo = array(
    array('value A',  1, $this),
    array('value b',  2, NULL),
    array('value X', 15, new Test)
);

我想象应该是这样的：

/*
 * @var array[][string|int|object|null] Description.
 */

- Guilherme Nascimento

---

@var array[] 一个混合对象数组。 - john Smith

@var mixed[] 一个混合对象数组。 - user557846

“mixed 表示参数可以接受多种（但不一定是全部）类型。“ （http://php.net/manual/de/language.pseudo-types.php）严格来说，这不适用于此处，因为内部值都是数组而不是混合类型。 - YMMD

Answer 1

根据 PHPDoc（FIG PSR-5 申请者）的最新草案，@var 标签已经弃用。他们建议使用@type 标签代替。

变量类型仍然是数组；该数组的内容会在描述中简要提到。

/**
 * @var array $foo An array of string elements.
 */

或者

/**
 * @type array $foo An array of string elements.
 */

如果变量可能包含除字符串以外的其他内容，我可能会说“一个混合元素的数组”，或者如果我知道具体可能是什么，我会说“一个bool|string|object元素的数组”。

如果变量本身可能是各种类型，我将列出它可能是的类型列表。

/**
 * @type bool|string|array $foo Mixed type, depending on result of baz().
 */

- Amgine

---

谢谢，也许是 @type \ArrayObject<\ArrayObject<string, integer, object>>？ - Guilherme Nascimento

PHP的变量有类型。数组是一个数组类型。数组有元素。类的实例是一个对象类型，它可能有属性。所以@type array $nameOfVariable 变量描述。在描述变量内容时，请简要说明。使用管道符号（'|'）分隔类型，因为内容可能是“这个或那个”类型。在文档中避免混淆非常重要，因此不要在指代“元素”时使用“对象”一词。 - Amgine

子数组应该在生成时进行文档记录。如果它是一个元素，就不需要进行文档记录。可以在描述中进行文档记录，例如 @type array $variable Holds arrays generated by Classname::arrayGeneratingMethod()。 - Amgine