Comment associative array in PHP Documentor
Solution 1
You can't document each key, but you can tell phpDocumentor what type it is.
You could do something like this:
/**
* Form the array like this:
* <code>
* $array = array(
* 'id' => 'foo', // the id
* 'class' => 'myClass', // the class
* );
*
* </code>
*
* @var array[string]string
*/
$array;
Solution 2
I would look at the WordPress Inline Documentation Reference for some hints, though it's not currently comprehensive.
Use @param or @var or @property, whichever is appropriate in your context
According to those guidelines, you might document your associative array like this:
/**
* @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'.
* }
*/
Solution 3
For me this works fine in PhpStorm for nice return value description:
/**
* @param string $requestUri
* @return array[
* 'controller' => string,
* 'action' => string
* ]
*/
Related videos on Youtube
Comments
-
Abenil almost 2 years
I use several associative arrays in my PHP application and I'm using PHP documentor to comment my sources. I never really did specify comments for the arrays in an array, but now I need to do that and don't know how.
$array = array('id' => 'test', 'class' => 'tester', 'options' => array('option1' => 1, 'option2' => 2))
How do I comment this array in the correct way for
@var
and@param
comments? I could do this like this, but I don't know if this is correct:@param string $array['id'] @param string $array['class'] @param int $array['options']['option1']
But how to do this for the
@var
part? -
Sepster almost 12 yearsHas this been confirmed to work with auto-complete/intellisense in any IDEs, I wonder? According to the phpDoc ABNF for type definitions, there's no allowance for a type to be specified for the array index. And it specifies array as
@var string[]
(thearray
component is only supposed to be present for "unspecified" arrays). -
Stephen Fuhry almost 12 years@Sepster I don't think most IDEs are smart enough to recognize this, unfortunately. Your mileage may vary, but I even find Zend Studio's implementation a bit lacking when it comes to this sort of accute type awareness.
-
faintsignal over 7 yearsUpdated link for ABNF mentioned in Sepster's comment: phpdoc.org/docs/latest/references/phpdoc/types.html
-
Andrew Sauder over 7 yearsThis notation for documenting array structures has never made it into official PHPDoc spec despite serious discussion in 2013-14 about adding it.
-
Ben Creasy over 7 yearsSeems to be some related discussion at github.com/phpDocumentor/phpDocumentor2/issues/650
-
Chad over 4 yearsTried this in Webstorm 2020.1 EAP for a param description and it mangled the help popup. In my experience this doesn't work.
-
luukvhoudt about 4 yearsThe example is confusing, it's not possible by looking at the
@var
annotation which type is used for the array key or value. Now I can't figure out if thestring
type hint inside or after the squared brackets is specifying the type of the key. -
Jordan Pickwell almost 4 yearsThe latest ABNF for types: github.com/php-fig/fig-standards/blob/master/proposed/…
-
Gogowitsch about 3 yearsThe WordPress guide seems similar to what Psalm recommends: psalm.dev/docs/annotating_code/type_syntax/array_types/…
-
Gherman about 3 yearsI think this answer may be misleading. It says "phpDocumentor". However the link actually leads to "PHPLint". I think it's a different software. There's no reason why PHPLint syntax would also be valid phpDoc syntax.