Question

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

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

@param CustomType $variablename

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

时

@param CustomType[] $variablename

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

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

除非我在参数说明中注意到这一点，但在类型中显示参数的数组似乎更清楚。

修改

使用phpDocumentor 2（与DocBlox合并）

@param CustomType[] $paramName

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

接受的答案已适当更新。

Answer 1

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

Answer 2

你能做的最好的事情是：

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

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

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

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

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

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

示例：

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

Answer 5

http://www.phpdoc.org/docs/latest/guides/types.html

上的phpdoc文档说明

阵列

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

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

有没有办法让phpDoc将对象数组作为参数进行记录？

5 个答案: