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

Question

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

@param CustomType $variablename

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

@param CustomType[] $variablename

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

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

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

РЕДАКТИРОВАТЬ

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

@param CustomType[] $paramName

, и, как отмечено в ответе @ Styx, PhpStorm поддерживает подсказки типов с помощьюэтот синтаксис.

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

Answer 1

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

Answer 2

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

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

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

Answer 3

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

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

Пример:

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

Answer 4

См. Следующие примеры из: 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
  */

Answer 5

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

массив

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

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