Eu estou lutando para escrever documentação legível e fácil de entender que descreve a estrutura de várias árvores para opções de matriz que são passadas para uma função.

Aqui está uma estrutura de array de exemplo.

$arr = array(
   'fields'=>array(
       'title'=>array('name'=>'Document.title','format'=>'string','readonly'=>true)
   )
);

Existem muitas opções possíveis para o array acima, mas isso é usado como um parâmetro para uma função que entende essa estrutura.

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

Eu gostaria de documentar como o array deve ser estruturado no PHPDoc, mas não tenho certeza qual é a abordagem correta.

Aqui está o que tenho agora.

/**
 * 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.
 **/

Meu problema é que quando o documento HTML é gerado, ele não é formatado muito bem. Além disso, não tenho certeza de que o texto acima explique claramente a estrutura da matriz.

Existe uma abordagem alternativa?