Комментировать ассоциативный массив в PHP-документе

Я использую несколько ассоциативных массивов в моем приложении PHP, и я использую PHP documentor для комментариев моих источников. Я никогда не задавал комментарии для массивов в массиве, но теперь мне нужно это сделать и не знаю, как это сделать.

$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?

Ответ 1

Вы не можете документировать каждую клавишу, но вы можете указать phpDocumentor, какой тип это.

Вы можете сделать что-то вроде этого:

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

Ответ 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'.
 * }
 */

Ответ 3

Для меня это прекрасно работает в PhpStorm для хорошего описания возвращаемого значения:

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