phpDoc 有没有办法将对象数组记录为参数？

Question

在 phpDoc 生成的文档中，我可以使 phpDoc 使用

为给定参数生成指向自定义类型定义的链接

@param CustomType $variablename

而且效果很好。但是，我目前正在记录的代码需要 CustomType[] 参数，即所述 CustomType 的数组。我希望文档清楚地表明需要一个数组，但是当我使用

@param CustomType[] $variablename

phpDoc 不再识别该类型，因此无法链接到它的定义。在这种情况下，这一点非常重要 - 我正在记录一个 API，该 API 需要提供一些相当复杂的类型。

我为此尝试了几种不同的语法，并且都将条目视为单独的变量类型或在文档中破坏类型识别。

除此之外，我只会在参数注释中注明，但在类型中显示参数的数组性似乎更清楚。

编辑

使用 phpDocumentor 2（与 DocBlox 合并）

@param CustomType[] $paramName

语法有效，正如@Styx 的回答中所述，PhpStorm 支持使用该语法进行类型提示。

已接受的答案已适当更新。

Answer 1

你能做的最好的就是：

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

这应该有助于读者了解 $variablename 的真实数据类型，同时表明对数组包含的内容的期望。

在使用 $variablename 中的成员并期望出现 CustomType 的属性/方法时，这不足以帮助 IDE 自动完成。目前真的没有办法得到这种行为。

Answer 2

新版 PHP 文档支持 /** @var sometype[] */ 语法。更复杂的是：/** @var (sometype|othertype)[] */。 http://www.phpdoc.org/docs/latest/guides/types.html#arrays PHPStorm 也支持这种语法。

Answer 3

请参阅以下示例： 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 4

http://www.phpdoc.org/docs/latest/guides/types.html 的 phpdoc 文档说明

数组

未知类型变量的集合。可以指定数组成员的类型，更多信息请参见数组章节。

而且...没有链接，也没有“关于数组”的章节。所以不，这看起来像是即将推出的功能。

Answer 5

注意：此答案是对其他答案的补充。

要记录一组对象，您可以使用@param ClassName[] $classInstance Description。 但请注意，在 PHP 7 中，您可以使用参数类型声明（类型提示），在这种情况下，类型必须是 array。

例子：

提示：您还应该使用declare(strict_types=1);