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

问题

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.

回答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.

回答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.

回答3:

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

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

回答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.

来源：https://stackoverflow.com/questions/9132062/is-there-a-way-for-phpdoc-to-document-an-array-of-objects-as-a-parameter

标签

arrays

phpdoc

custom-type