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

Posted 2023-02-22

技术标签:

【中文标题】phpDoc 有没有办法将对象数组记录为参数？【英文标题】：Is there a way for phpDoc to document an array of objects as a parameter? 【发布时间】：2012-02-26 06:32:04 【问题描述】：

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

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

@param CustomType $variablename

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

@param CustomType[] $variablename

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

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

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

编辑

使用 phpDocumentor 2（与 DocBlox 合并）

@param CustomType[] $paramName

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

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

【问题讨论】：

可能重复：***.com/questions/778564/… 不是真的；它们是免费的——他问的是 IDE 中的类型提示，而我的是关于 phpDoc 文档本身的——在我的例子中，tpe 提示只是一个很好的副作用。要记录关联数组的形状，请参阅***.com/questions/14612773/… - 一种方法是github.com/phpDocumentor/fig-standards/issues/30#issue-20061866 【参考方案1】：

你能做的最好的就是：

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

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

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

【讨论】：

当然，正在努力使数据类型签名语法为“CustomObject[]”=>“自定义对象成员数组”。一旦它在文档生成器中可用，我希望 IDE 可能会支持它的含义。这几乎是我已经接受的，但是到 docblox 的链接可能值得关注。谢谢！【参考方案2】：

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

【讨论】：

【参考方案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
  */

【讨论】：

在 phpdoc 网站/参考 phpdoc.org/docs/latest/references/phpdoc/index.html 或建议的 PSR5 文档 github.com/phpDocumentor/fig-standards/blob/master/proposed/… 上没有提及 @opt_param 被支持 - 无论谁创作了您复制的 docblock，也可能已经输入@this_wont_work_param (!) 在github.com/phpDocumentor/phpDocumentor2/issues/650 讨论记录数组的键【参考方案4】：

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