Best way to document Array options in PHPDoc?

Question

I'm struggling to write readable and easy to understand documentation that describes the multi-tree structure for Array options that are passed to a function.

Here is an example array structure.

$arr = [    'fields' => [        'title' => [            'name'     => 'Document.title',            'format'   => 'string',            'readonly' => true        ]    ] ]; 

There are many possible options for the above array, but this is used as a parameter to a function that understands that structure.

function doSomething(array $arr) { ... } 

I'd like to document how the array should be structured in PHPDoc, but I'm not sure what the correct approach is.

Here is what I have now.

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

My problem is that when the HTML document is generated, it's not formatted very nicely. Additionally, I'm not sure the above is clearly explains the array structure.

Is there an alternative approach?

Answer 1

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.

Answer 2

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);