Как документировать массив [тип]?

Question

Скажем, у меня есть такая функция:

function theFunction() {
    $arr = array();
    for ($i=0;$i<10;$i++) {
        $arr[] = new theObject($i);
    }
    return $arr;
}

Мне нужно документировать тип возврата функции. Я мог бы, конечно, просто использоватьarray, но это не предоставляет всю информацию, которая может быть предоставлена, и не говорит разработчику много об истинной природе функции.

Как мне документировать тип "массив [тип]" в PHPDoc?

Answer 1

Из документации phpDocumentor

Значение, представленное Type, может быть массивом. Тип ДОЛЖЕН быть определен в соответствии с форматом одной из следующих опций:

1. не указано, определение содержимого представленного массива не приводится. Пример: @return array

2. указанный тип содержит единственный тип, определение типа информирует читателя о типе каждого элемента массива. В качестве элемента для данного массива ожидается только один тип.

   Пример: @return int[]

   Обратите внимание, что mixed также является одним типом, и с помощью этого ключевого слова можно указать, что каждый элемент массива содержит любой возможный тип.

3. указанный, содержащий несколько типов, определение типа информирует читателя о типе каждого элемента массива. Каждый элемент может быть любого из указанных типов. Пример: @return (int|string)[]

   Заметка
   многие IDE, вероятно, еще не поддерживают эту нотацию.

Answer 2

В PHPDoc вы можете сделать следующее для подсказок типа:

@var array<\My\Folder\ClassName>

Answer 3

Если я правильно помню, вы предоставляете тип возврата и описание, вы не можете поместить его в описание?

/**
 * blah
 * @return array array of types
 */

Answer 4

В PHP 7.4+ вы можете использовать объявления типов для обеспечения возвращаемого типа метода.

Хотя он не предназначен для документирования, он справляется с документированием лучше, чем phpDocs.

В вашем случае вы можете сделать:

      function theFunction(): array {
    return [];
}