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

and that works great. However, the code I'm currently documenting requires CustomType[] parameters, i.e. an array of said CustomType. I want the documentation to be clear that an array is required, but when I use

@param CustomType[] $variablename

phpDoc no longer recognizes the type, and thus can't link to it's definition. This is pretty important in this case - I'm documenting an API that has some fairly complex types that need to be provided.

I've tried several different syntaxes for this and all either treat the entries as separate variable types or break type recognition in the documentation.

Barring this I'll just note it in the parameter note, but it seems more clear to show the array-ness of the parameter in the type.

EDIT

With phpDocumentor 2 (which merged with DocBlox) the

@param CustomType[] $paramName

syntax works, and as noted in @Styx's answer PhpStorm supports type-hinting with that syntax.

Accepted answer updated appropriately.

Arnhem

Possible duplicate: #779064 – Boot

not really; they're complimentary - he's asking about type-hinting in the IDE, whereas mine was about the phpDoc documentation itself - the tpe-hinting is just a nice side-effect in my case. – Arnhem

To document the shape of an an associative array, see #14613273 - one approach is at github.com/phpDocumentor/fig-standards/issues/30#issue-20061866 – Aarau

Answer 1

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.

Junkman

Answer 2

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.

Cotoneaster

Granted, there is an effort in progress to have a datatype signature syntax of "CustomObject[]" => "an array of CustomObject members". Once it is available in a documentation generator, I expect IDEs will probably follow to support its meaning. – Cotoneaster

that's pretty much what I've resigned myself to, but the link to docblox might be worth following. Thanks! – Arnhem

Answer 3

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);

Comanchean

Answer 4

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

Kerril

There is no mention of @opt_param being supported on the phpdoc website/reference phpdoc.org/docs/latest/references/phpdoc/index.html or in the proposed PSR5 documentation at github.com/phpDocumentor/fig-standards/blob/master/proposed/… - whoever authored the docblock you copied in may as well have typed in @ this_wont_work_param (!) – Marquez

Documenting the keys of an array is under discussion at github.com/phpDocumentor/phpDocumentor2/issues/650 – Aarau

Answer 5

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.

Linis