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

Answer 1

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:

    

        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.
                
            
        
    
 

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