PHP Documentor 中的注释关联数组

Posted 2023-02-22

【中文标题】PHP Documentor 中的注释关联数组

【英文标题】：Comment associative array in PHP Documentor

【发布时间】：2011-02-12 09:52:09

【问题描述】：

我在我的 php 应用程序中使用了几个关联数组，并且我正在使用 PHP 文档器来注释我的源代码。我从来没有真正为数组中的数组指定 cmets，但现在我需要这样做并且不知道如何。

$array = array('id' => 'test', 'class' => 'tester', 'options' => array('option1' => 1, 'option2' => 2))

如何以正确的方式为@var 和@param cmets 注释此数组？ 我可以这样做，但我不知道这是否正确：

@param string $array['id']
@param string $array['class']
@param int $array['options']['option1']

但是如何为@var 部分执行此操作？

【参考方案1】：

对我来说，这在 PhpStorm 中可以很好地描述返回值：

/**
 * @param string $requestUri
 * @return array[
 *  'controller' => string,
 *  'action' => string
 * ]
 */

【讨论】：

在 Webstorm 2020.1 EAP 中尝试了此参数描述，但它破坏了帮助弹出窗口。根据我的经验，这是行不通的。

【参考方案2】：

我会查看WordPress Inline Documentation Reference 以获得一些提示，尽管它目前并不全面。

使用@param 或@var 或@property，以适合您的上下文为准

根据这些指南，您可以像这样记录您的关联数组：

/**
 * @property array $my_array 
 *     An array of parameters that customize the way the parser works.
 *
 *     @type boolean $ignore_whitespace Whether to gobble up whitespace. Default true.
 *     @type string $error_level What the error reporting level is. Default 'none'.
 *                               Accepts 'none', 'low', 'high'.
 * 
 */

【讨论】：

尽管在 2013-14 年就添加它进行了认真讨论，但这种用于记录数组结构的符号从未进入官方 PHPDoc 规范。

好像是github.com/phpDocumentor/phpDocumentor2/issues/650的一些相关讨论

WordPress 指南似乎与 Psalm 推荐的类似：psalm.dev/docs/annotating_code/type_syntax/array_types/…

【参考方案3】：

您不能记录每个键，但you can tell phpDocumentor what type it is。

你可以这样做：

/**
 * Form the array like this:
 * <code>
 * $array = array(
 *   'id'      => 'foo',          // the id
 *   'class'   => 'myClass',     // the class
 * );
 * 
 * </code>
 *
 * @var array[string]string 
 */
$array;

【讨论】：

我想知道，这是否已确认可在任何 IDE 中与自动完成/智能感知一起使用？根据the phpDoc ABNF for type definitions，不允许为数组索引指定类型。并且它将数组指定为@var string[]（array 组件只应该出现在“未指定”数组中）。

@Sepster 不幸的是，我认为大多数 IDE 都不够聪明，无法识别这一点。你的情况可能会有所不同，但我什至发现 Zend Studio 的实现在这种精确的类型感知方面有点欠缺。

Sepster 评论中提到的 ABNF 更新链接：phpdoc.org/docs/latest/references/phpdoc/types.html

该示例令人困惑，无法通过查看 @var 注释来确定数组键或值使用哪种类型。现在我无法弄清楚方括号内部或之后的 string 类型提示是否指定了键的类型。

最新的 ABNF 类型：github.com/php-fig/fig-standards/blob/master/proposed/…