Multiline array shapes with 'comments'

[jlwoolf]

Feature request

For types that involve more complex associative arrays, it is nice to know what each of key/value pairs are for. Does there exist a way to have 'type comments' that allow you to insert comments/descriptions in multiline array types?

For example, below is an associative array that has a bunch of expected key values, along with 'comments' to help describe what each key is for. Is there a standard for psalm to do this.

/**
 *
 * @var array<
 *  string,                   // name of the rule
 *  array{
 *   params: array<           // list of parameters defined by the rule
 *    array{
 *     key: string,           // the key used to identify the value in the POST
 *     nullOK: bool,          // the key used to identify the value in the POST
 *     blankOK: bool,         // whether the param's value can be an empty string
 *     type: string,          // the type of value
 *     regExp?: string,       // regular expression used for validation if the type is 'regex'
 *     context?: string,      // extra data required for validation (currenlty only used if type is 'signed')
 *     name?: string,         // human readable name for the param (used by error messages, defaults to 'key')
 *     description?: string,  // a description of the parameter
 *     list?: bool,           // whether the param's value is a list
 *     delim?: string,        // delimeter to split the list on (e.g. [val => 'this,is,a,list', delim => ','])
 *     trim?: string,         // whether to strip whitespace from elements in list
 *     trimLevel?: string,    // 0 to trim whitespace from beginning and end of items,
 *     minErr?: int,          // minimum length of the param's value
 *     maxErr?: int,          // maximum length of the param's value
 *     allowedVals?: array,   // a list of allowed values
 *     blackList?: array      // a list of blacklisted/blocked values
 *    }>,
 *   handlers: array<
 *    string,                 // name of the handler
 *    array{
 *     func: string,          // the name of the function in the app's validator (e.g. '\ESP\app\Validator::func')
 *     extraArgs?: array,     // any parameters that are not $action, $post, or $postIn - ORDER MATTERS
 *     return?: bool          // whether error's are returned as a json or an exception is thrown (defaults to false)
 *    }>
 * }>
 */
public static $rules = [];

This would be incredibly useful. Thanks!