Best Way To Document Array Options In PHPDoc?

Answer :

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