Я использую несколько ассоциативных массивов в моем приложении 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?
Вы не можете документировать каждую клавишу, но вы можете указать phpDocumentor, какой тип это.
Вы можете сделать что-то вроде этого:
/**
* Form the array like this:
* <code>
* $array = array(
* 'id' => 'foo', // the id
* 'class' => 'myClass', // the class
* );
*
* </code>
*
* @var array[string]string
*/
$array;
Я бы посмотрел на 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'.
* }
*/
Для меня это прекрасно работает в PhpStorm для хорошего описания возвращаемого значения:
/**
* @param string $requestUri
* @return array[
* 'controller' => string,
* 'action' => string
* ]
*/