Best way to document Array options in PHPDoc?

A bit too late to the party but this is how I do it instead:

/** * Class constructor. * * @param array $params Array containing the necessary params. *    $params = [ *      'hostname'     => (string) DB hostname. Required. *      'databaseName' => (string) DB name. Required. *      'username'     => (string) DB username. Required. *      'password'     => (string) DB password. Required. *      'port'         => (int) DB port. Default: 1433. *      'sublevel'     => [ *          'key' => (\stdClass) Value description. *      ] *    ] */ public function __construct(array $params){}

Think it's quite clean and easy to understand what $params should be.

I wrote a plugin for phpstorm that allows specifying keys like this:

(basically just a slightly stricter version of @siannone's format)

/** * @param array $arr = [ *     'fields' => [ // Defines the feilds to be shown by scaffolding *         $anyKey => [ *             'name' => 'sale', // Overrides the field name (default is the array key) *             'model' => 'customer', // (optional) Overrides the model if the field is a belongsTo associated value. *             'width' => '100px', // Defines the width of the field for paginate views. Examples are "100px" or "auto" *             'align' => 'center', // Alignment types for paginate views (left, right, center) *             'format' => 'nice', // Formatting options for paginate fields. Options include ('currency','nice','niceShort','timeAgoInWords' or a valid Date() format) *             'title' => 'Sale', // Changes the field name shown in views. *             'desc' => 'A deal another person that results in money', // The description shown in edit/create views. *             'readonly' => false, // True prevents users from changing the value in edit/create forms. *             'type' => 'password', // Defines the input type used by the Form helper *             'options' => ['option1', 'option2'], // Defines a list of string options for drop down lists. *             'editor' => false, // If set to True will show a WYSIWYG editor for this field. *             'default' => '', // The default value for create forms. *         ], *     ], * ] */public static function processForm($arr){    $fieldName = 'sale';    $arr['fields'][$fieldName][''];}

It allows to specify @return keys as well:

/** * @return array [ *     'success' => true, *     'formObject' => new Form, *     'errors' => [], * ] */public static function processForm($arr);

Just adding some tabulation will make it look good and easy to understand

/** * Holds configuration settings for each field in a model. * Defining the field options * * array['fields']              array Defines the fields to be shown by scaffolding. *          [fieldName]         array Defines the options for a field, or just enables the field if array is not applied. *              ['name']        string Overrides the field name (default is the array key) *              ['model']       string (optional) Overrides the model if the field is a belongsTo associated value. *              ['width']       string Defines the width of the field for paginate views. Examples are "100px" or "auto" *              ['align']       string Alignment types for paginate views (left, right, center) *              ['format']      string Formatting options for paginate fields. Options include ('currency','nice','niceShort','timeAgoInWords' or a valid Date() format) *              ['title']       string Changes the field name shown in views. *              ['desc']        string The description shown in edit/create views. *              ['readonly']    boolean True prevents users from changing the value in edit/create forms. *              ['type']        string Defines the input type used by the Form helper (example 'password') *              ['options']     array Defines a list of string options for drop down lists. *              ['editor']      boolean If set to True will show a WYSIWYG editor for this field. *              ['default']     string The default value for create forms. * * @param array $arr (See above) * @return Object A new editor object. **/

A nested list approach:

<ul>    <li>        array['fields'] array Defines the fields to be shown by scaffolding.        <ul>            <li>                [fieldName]             array Defines the options for a field, or just enables the field if array is not applied.                <ul>                    <li> ['name']       <i><u>string</u></i> Overrides the field name (default is the array key) </li>                    <li> ['model']      <i><u>string</u></i> (optional) Overrides the model if the field is a belongsTo associated value.</li>                    <li> ['width']      <i><u>string</u></i> Defines the width of the field for paginate views. Examples are "100px" or "auto"</li>                    <li> ['align']      <i><u>string</u></i> Alignment types for paginate views (left, right, center)</li>                    <li> ['format']     <i><u>string</u></i> Formatting options for paginate fields. Options include ('currency','nice','niceShort','timeAgoInWords' or a valid Date() format)</li>                    <li> ['title']      <i><u>string</u></i> Changes the field name shown in views.</li>                    <li> ['desc']       <i><u>string</u></i> The description shown in edit/create views.</li>                    <li> ['readonly']   <i><u>boolean</u></i> True prevents users from changing the value in edit/create forms.</li>                    <li> ['type']       <i><u>string</u></i> Defines the input type used by the Form helper (example 'password')</li>                    <li> ['options']    <i><u>array</u></i> Defines a list of string options for drop down lists.</li>                    <li> ['editor']     <i><u>boolean</u></i> If set to True will show a WYSIWYG editor for this field.</li>                    <li> ['default']    <i><u>string</u></i> The default value for create forms.</li>                </ul>            </li>        </ul>    </li> </ul>

Result:

• array['fields'] array Defines the fields to be shown by scaffolding.
  • [fieldName] array Defines the options for a field, or just enables the field if array is not applied.
    • ['name'] string Overrides the field name (default is the array key)
    • ['model'] string (optional) Overrides the model if the field is a belongsTo associated value.
    • ['width'] string Defines the width of the field for paginate views. Examples are "100px" or "auto"
    • ['align'] string Alignment types for paginate views (left, right, center)
    • ['format'] string Formatting options for paginate fields. Options include ('currency','nice','niceShort','timeAgoInWords' or a valid Date() format)
    • ['title'] string Changes the field name shown in views.
    • ['desc'] string The description shown in edit/create views.
    • ['readonly'] boolean True prevents users from changing the value in edit/create forms.
    • ['type'] string Defines the input type used by the Form helper (example 'password')
    • ['options'] array Defines a list of string options for drop down lists.
    • ['editor'] boolean If set to True will show a WYSIWYG editor for this field.
    • ['default'] string The default value for create forms.

If you want it to look fancy, with a bit of Css it will make wonders! xd