Есть ли способ для phpDoc документировать массив объектов в качестве параметра?

В документации, созданной phpDoc, я могу заставить phpDoc сгенерировать ссылку на определение пользовательского типа для данного параметра с помощью

@param CustomType $variablename

и это отлично работает. Тем не менее, код, который я сейчас документирую, требует параметров CustomType [], то есть массива указанного CustomType. Я хочу, чтобы в документации было ясно, что требуется массив, но когда я использую

@param CustomType[] $variablename

phpDoc больше не распознает тип и, следовательно, не может ссылаться на его определение. Это очень важно в этом случае - я документирую API, который имеет довольно сложные типы, которые необходимо предоставить.

Я пробовал несколько разных синтаксисов для этого, и все они рассматривают записи как отдельные типы переменных или распознавания типа разрыва в документации.

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

ИЗМЕНИТЬ

С phpDocumentor 2 (который слился с DocBlox)

@param CustomType[] $paramName

Синтаксис

работает, и, как отмечено в @Styx, ответ PhpStorm поддерживает тип-намек с этим синтаксисом.

Принятый ответ обновлен соответствующим образом.

Ответ 1

Новая версия поддержки PHP doc /** @var sometype[] */. Еще сложнее: /** @var (sometype|othertype)[] */. http://www.phpdoc.org/docs/latest/guides/types.html#arrays PHPStorm также поддерживает этот синтаксис.

Ответ 2

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

@param array $variablename an array of {@link CustomType} objects

Это должно помочь читателю понять истинный тип данных $variablename, указав ожидание того, что содержит массив.

Этого недостаточно, чтобы помочь автозаполнению IDE при использовании члена из $varablename и ожидать появления свойств/методов CustomType. В настоящее время нет способа получить это поведение.

Ответ 3

См. следующие примеры из: https://code.google.com/p/google-api-php-client/source/checkout где описывается структура массива входных параметров.

/**
  * Set the OAuth 2.0 access token using the string that resulted from calling authenticate()
  * or Google_Client#getAccessToken().
  * @param string $accessToken JSON encoded string containing in the following format:
  * {"access_token":"TOKEN", "refresh_token":"TOKEN", "token_type":"Bearer",
  *  "expires_in":3600, "id_token":"TOKEN", "created":1320790426}
  */


/**
  * Insert a new file. (files.insert)
  *
  * @param Google_DriveFile $postBody
  * @param array $optParams Optional parameters.
  *
  * @opt_param bool convert Whether to convert this file to the corresponding Google Docs format.
  * @opt_param string targetLanguage Target language to translate the file to. If no sourceLanguage is provided, the API will attempt to detect the language.
  * @opt_param string sourceLanguage The language of the original file to be translated.
  * @opt_param string ocrLanguage If ocr is true, hints at the language to use. Valid values are ISO 639-1 codes.
  * @opt_param bool pinned Whether to pin the head revision of the uploaded file.
  * @opt_param bool ocr Whether to attempt OCR on .jpg, .png, or .gif uploads.
  * @opt_param string timedTextTrackName The timed text track name.
  * @opt_param string timedTextLanguage The language of the timed text.
  * @return Google_DriveFile
  */

Ответ 4

Примечания к документации phpdoc на http://www.phpdoc.org/docs/latest/guides/types.html

массив

Набор переменных неизвестного типа. Можно указать типы элементов массива, более подробную информацию см. В главе о массивах.

И... нет ссылки и нет главы "на массивах". Нет, это похоже на предстоящую функцию.

Ответ 5

ПРИМЕЧАНИЕ. Этот ответ является дополнением к другим ответам.

Чтобы документировать массив объектов, вы можете использовать @param ClassName[] $classInstance Description. Но имейте в виду, что с PHP 7 вы можете использовать объявления типа аргумента (типы подсказок), и в этом случае тип должен быть array.

Пример:

СОВЕТ. Вы также должны использовать declare(strict_types=1);