title: Best way to document Array options in PHPDoc?
body: <p>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.</p>
  
  <p>Here is an example array structure.</p>
  
  <pre><code>$arr = [
     'fields' =&gt; [
         'title' =&gt; [
             'name'     =&gt; 'Document.title',
             'format'   =&gt; 'string',
             'readonly' =&gt; true
         ]
     ]
  ];
  </code></pre>
  
  <p>There are many possible options for the above array, but this is used as a parameter to a function that understands that structure.</p>
  
  <pre><code>function doSomething(array $arr) { ... }
  </code></pre>
  
  <p>I'd like to document how the array should be structured in PHPDoc, but I'm not sure what the correct approach is.</p>
  
  <p>Here is what I have now.</p>
  
  <pre><code>/**
   * 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.
   **/
  </code></pre>
  
  <p>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.</p>
  
  <p>Is there an alternative approach?</p>