Add short description for an array that has a described hash

[ericandrewlewis]

In the current PHPDoc standards, describing hashes does not afford for giving a short description to an array element in conjunction with the hash details.

Currently:

/**
 * Initializes this class with the given options.
 *
 * @param array $options {
 *     @type boolean $required Whether this element is required
 *     @type string  $label    The display name for this element
 * }
 */
public function __construct(array $options = array())
{
    <...>
}

As @mvriel has been working with us (the WordPress inline documentation team) on this, we've come up with the standard of putting the description inside the container block for describing hash elements, a la:

/**
 * Initializes this class with the given options.
 *
 * @param array $options {
 *     A description of this array.
 *
 *     @type boolean $required Whether this element is required
 *     @type string  $label    The display name for this element
 * }
 */
public function __construct(array $options = array())
{
    <...>
}

[mvriel]

I have an update ready locally, just not found the time to finish it

[lisachenko]

👍 for array hash documentation

[donquixote]

To re-post the idea from the other thread:

/**
 * @param {
 *   type: string
 *   query: SelectInterface
 *     This is the query object.
 *   options: {
 *     color: string = 'blue'
 *   }
 * }[] $items
 *   And now a description about the entire param.
 * @param $options {
 *   # Or maybe put a description like this?
 *   color: string
 *     The colors of PDO.
 * }
 * @param string $label
 *   This param adds a label.
 */

I somehow don't like the @type all over the place. One @param should be enough for my taste, then the nested stuff should follow a simpler syntax. How exactly this looks like is a matter of discussion, I personally prefer sth around yml or json style.

[66Ton99]

Here you describe values but what about keys?

if I need return structured array like:

array(
    '2014-01-04' => '4 Jan 2014',
    ...
);

and I want to describe key and value?

[mvriel]

@66Ton99 for the example you offer you would not need an elaborate piece because you don't have fixed keys; the following would suffice:

/** @type array<string, string> the key represents a date in the MySQL format (YYYY-MM-DD) where the value represents its counterpart in human-readable short notation (i.e. `4 Jan 2014`).

[mvriel]

I am going to close this issue as it is basically a duplicate of #7; let's continue there