Is there a way for phpDoc to document an array of objects as a parameter?

Question

In phpDoc-generated documentation I can cause phpDoc to generate a link to a custom type definition for a given param using

@param CustomType $variablename
         


        

Answer 1

See the following examples from: https://code.google.com/p/google-api-php-client/source/checkout where is described the array structure of input parameters.

/**
  * 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 2

The phpdoc documentation notes at http://www.phpdoc.org/docs/latest/guides/types.html

array

A collection of variables of unknown type. It is possible to specify the types of array members, see the chapter on arrays for more information.

And... there is no link and no chapter "on arrays". So no, this looks like a forthcoming feature.

Answer 3

New version of PHP doc support /** @var sometype[] */ syntax. Even more complicated: /** @var (sometype|othertype)[] */. http://www.phpdoc.org/docs/latest/guides/types.html#arrays PHPStorm also support this syntax.

Answer 4

NOTE: This answer is a complement to the other answers.

To document an array of objects you can use @param ClassName[] $classInstance Description. But be aware that with PHP 7 you can use argument type declarations (type hints) and in this case, the type must be array.

Example:

TIP: You should also use declare(strict_types=1);

Answer 5

The best you can do is:

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

This should help the reader realize the true datatype of $variablename, while indicating the expectation of what the array contains.

This won't be enough to help an IDE's autocompletion when it comes to using a member from $variablename and expecting properties/methods of CustomType to appear. There's really no way to get that behavior currently.