Staram się pisać czytelną i łatwą do zrozumienia dokumentację, która opisuje strukturę wielu drzew dla opcji macierzy przekazywanych do funkcji.

Oto przykładowa struktura tablicy.

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

Istnieje wiele możliwych opcji dla powyższej tablicy, ale jest ona używana jako parametr dla funkcji, która rozumie tę strukturę.

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

Chciałbym udokumentować, jak tablica powinna być skonstruowana w PHPDoc, ale nie jestem pewien, jakie jest właściwe podejście.

Oto, co mam teraz.

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

Mój problem polega na tym, że kiedy dokument HTML jest generowany, nie jest on zbyt ładnie sformatowany. Ponadto nie jestem pewien, czy powyższe wyjaśnienie wyraźnie wyjaśnia strukturę tablicy.

Czy istnieje alternatywne podejście?