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?
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:
<ul>
<li>
array['fields'] array Defines the fields to be shown by scaffolding.
<ul>
<li>
[fieldName] array Defines the options for a field, or just enables the field if array is not applied.
<ul>
<li> ['name'] <i><u>string</u></i> Overrides the field name (default is the array key) </li>
<li> ['model'] <i><u>string</u></i> (optional) Overrides the model if the field is a belongsTo associated value.</li>
<li> ['width'] <i><u>string</u></i> Defines the width of the field for paginate views. Examples are "100px" or "auto"</li>
<li> ['align'] <i><u>string</u></i> Alignment types for paginate views (left, right, center)</li>
<li> ['format'] <i><u>string</u></i> Formatting options for paginate fields. Options include ('currency','nice','niceShort','timeAgoInWords' or a valid Date() format)</li>
<li> ['title'] <i><u>string</u></i> Changes the field name shown in views.</li>
<li> ['desc'] <i><u>string</u></i> The description shown in edit/create views.</li>
<li> ['readonly'] <i><u>boolean</u></i> True prevents users from changing the value in edit/create forms.</li>
<li> ['type'] <i><u>string</u></i> Defines the input type used by the Form helper (example 'password')</li>
<li> ['options'] <i><u>array</u></i> Defines a list of string options for drop down lists.</li>
<li> ['editor'] <i><u>boolean</u></i> If set to True will show a WYSIWYG editor for this field.</li>
<li> ['default'] <i><u>string</u></i> The default value for create forms.</li>
</ul>
</li>
</ul>
</li>
</ul>
Result:
If you want it to look fancy, with a bit of Css it will make wonders! xd