Comment associative array in PHP Documentor

Question

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, b

Answer 1

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

Answer 2

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;

Answer 3

For me this works fine in PhpStorm for nice return value description:

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