PHP Documentor中的注释关联数组

Question

我在PHP应用程序中使用了几个关联数组,我使用PHP文档来评论我的源代码.我从来没有真正为数组中的数组指定注释,但现在我需要这样做而不知道如何.

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

如何以正确的方式@var和@param评论对此数组进行注释？我可以这样做,但我不知道这是否正确:

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

但是如何为这@var部分做到这一点？

Answer 1

你不能记录每个键,但你可以告诉phpDocumentor它是什么类型.

你可以这样做:

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

Answer 2

Phpstorm 中的工作原理是：

/**
 * @return array{ hand: Hand, card: CardType | null }
 */

Answer 3

我会看一下WordPress内联文档参考资料中的一些提示,尽管它目前还不全面.

使用@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'.
 * }
 */

Answer 4

对我来说，这在 PhpStorm 中很好用，以获得很好的返回值描述：

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