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, ie 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.
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.
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.
请参阅以下示例：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
*/
上一篇: 成员变量和@var phpdoc类型提示