phpDoc有办法将对象数组作为参数进行文档化吗？

Question

在phpDoc生成的文档中，我可以使用以下方法使phpDoc生成一个到给定参数自定义类型定义的链接。

@param CustomType $variablename

这很好用。然而，我现在要记录的代码需要CustomType[]参数，即所需的CustomType数组。我希望文档清楚地说明需要一个数组，但是当我使用

。

@param CustomType[] $variablename

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

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

如果不能解决，我将在参数注释中注明它，但在类型中显示参数的数组性质似乎更清晰。

编辑

使用与DocBlox合并的phpDocumentor 2后，

@param CustomType[] $paramName

语法可行，正如 @Styx 的答案中所提到的，PhpStorm 支持该语法的类型提示。

已相应地更新了接受的答案。

- cori

---

可能是重复问题：https://dev59.com/WHRA5IYBdhLWcg3w8SeJ - Benjamin Crouzier

并不完全一样；他在问IDE中的类型提示，而我的问题是关于phpDoc文档本身的 - 在我的情况下，类型提示只是一个很好的副作用。 - cori

要记录关联数组的形状，请参见 https://dev59.com/dW3Xa4cB1Zd3GeqPjt9j?noredirect=1&lq=1 - 其中一种方法在 https://github.com/phpDocumentor/fig-standards/issues/30#issue-20061866 上。 - Ben Creasy

Answer 1

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

- Styx

Answer 2

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

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

例如：

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

- SandroMarques

Answer 3

您可以尽力做到以下几点：

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

这应该帮助读者意识到$variablename的真实数据类型，并指示数组包含的内容的预期。

然而，当涉及到使用$variablename的成员并期望CustomType的属性/方法出现时，这是不足够的，这对IDE的自动完成帮助不大。目前真的没有办法获得这种行为。

- ashnazg

---

目前正在进行一项工作，旨在实现数据类型签名语法“CustomObject[]” => “CustomObject成员数组”。一旦它在文档生成器中可用，我预计IDE将会跟进以支持其含义。 - ashnazg

这基本上是我所接受的，但 docblox 的链接可能值得关注。谢谢！ - cori

Answer 4

请查看以下来自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
  */

- Marko Novakovic

---

在phpdoc网站/参考http://phpdoc.org/docs/latest/references/phpdoc/index.html上或在提议的PSR5文档https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md中，都没有提到支持@opt_param标记-你复制的docblock的作者可能就像输入 @ this_wont_work_param（！）一样。 - kguest

数组键的文档化正在 https://github.com/phpDocumentor/phpDocumentor2/issues/650 上讨论。 - Ben Creasy

Answer 5

phpdoc文档记录在http://www.phpdoc.org/docs/latest/guides/types.html中。

数组

一组未知类型的变量。可以指定数组成员的类型，请参阅有关数组的章节以获取更多信息。

然而...没有链接和"有关数组"的章节。因此，这看起来像是即将推出的功能。

- William Entriken