在PHPDoc中文档数组选项的最佳方式？ [英] Best way to document Array options in PHPDoc?

问题描述

我很难写出可读和易于理解的文档，它描述了传递给函数的Array选项的多树结构。

这里是一个示例数组结构。

  $ arr = array（
'fields'=& title'=> array（'name'=>'Document.title'，'format'=>'string'，'readonly'=> true）
）
）; 
  

上面的数组有很多可能的选项，但是这用作函数的参数了解此结构。

  function doSomething（array $ arr）{...} 
  

我想在PHPDoc中记录数组的结构，但我不知道正确的方法是什么。

这是我现在的。

  / ** 
 *保留模型中每个字段的配置设置。 
 *定义字段选项
 * 
 * array ['fields'] array定义要通过脚手架显示的字段。 
 * array ['fields'] [fieldName] array定义字段的选项，或者只是在未应用数组时启用字段。 
 * array ['fields'] [fieldName] ['name'] string覆盖字段名称（默认是数组键）
 * array ['fields'] [fieldName] string（可选）如果字段是belongsTo assoicated值，则覆盖模型。 
 * array ['fields'] [fieldName] ['width'] string定义分页视图的字段宽度。示例是100px或auto
 * array ['fields'] [fieldName] ['align'] string分页视图（左，右，中）的对齐类型
 * array ['fields '] [fieldName] ['format'] string分页字段的格式化选项。选项包括（'currency'，'nice'，'niceShort'，'timeAgoInWords'或有效的Date（）格式）
 * array ['fields'] [fieldName] ['title'] string更改字段名称如视图所示。 
 * array ['fields'] [fieldName] ['desc'] string编辑/创建视图中显示的描述。 
 * array ['fields'] [fieldName] ['readonly'] boolean True防止用户在编辑/创建表单中更改值。 
 * array ['fields'] [fieldName] ['type'] string定义Form helper使用的输入类型（example'password'）
 * array ['fields'] [fieldName] 'options'] array定义下拉列表的字符串选项列表。 
 * array ['fields'] [fieldName] ['editor'] boolean如果设置为True，将显示此字段的WYSIWYG编辑器。 
 * array ['fields'] [fieldName] ['default'] string创建表单的默认值。 
 * 
 * @param array $ arr（见上文）
 * @return Object一个新的编辑器对象。我的问题是，当生成HTML文档时，它没有格式化，因为它是一个HTML文档。非常好。另外，我不确定上面是否清楚地解释了数组结构。
 
 
 
是否有替代方法？
 
 
 
  / 
 ** 
 *保存模型中每个字段的配置设置。 
 *定义字段选项
 * 
 * array ['fields'] array定义要通过框架显示的字段。 
 * [fieldName] array定义字段的选项，或者仅在未应用数组时启用字段。 
 * ['name'] string覆盖字段名（默认是数组键）
 * ['model'] string（可选）如果字段是belongsTo关联值，则覆盖模型。 
 * ['width'] string定义分页视图的字段宽度。示例是100px或auto
 * ['align'] string分页视图（左，右，中）的对齐类型
 * ['format'] string分页字段的格式化选项。选项包括（'currency'，'nice'，'niceShort'，'timeAgoInWords'或有效的Date（）格式）
 * ['title'] string更改视图中显示的字段名称。 
 * ['desc'] string编辑/创建视图中显示的描述。 
 * ['readonly'] boolean True防止用户在编辑/创建表单中更改值。 
 * ['type'] string定义Form帮助器使用的输入类型（示例'password'）
 * ['options'] array定义下拉列表的字符串选项列表。 
 * ['editor'] boolean如果设置为True，将显示此字段的WYSIWYG编辑器。 
 * ['default'] string创建表单的默认值。 
 * 
 * @param array $ arr（见上文）
 * @return Object一个新的编辑器对象。 
 ** / 
  
嵌套列表方法：
 < ul> 
< li> 
 array ['fields'] array定义要通过框架显示的字段。 
< ul> 
< li> 
 [fieldName] array定义字段的选项，或者仅当不应用数组时启用字段。 
< ul> 
< li> ['name']< i>< u> string< / u>< / i>覆盖字段名称（默认为数组键）< / li> 
< li> ['model']< i>< u> string< / u>< / i> （可选）如果字段是belongsTo关联值，则覆盖模型。< / li> 
< li> ['width']< i>< u> string< / u>< / i>定义分页视图的字段宽度。示例为100px或auto< / li> 
< li> ['align']< i>< u> string< / u>< / i>分页视图的对齐方式（左，右，中）< / li> 
< li> ['format']< i>< u> string< / u>< / i>分页字段的格式化选项。选项包括（'currency'，'nice'，'niceShort'，'timeAgoInWords'或有效的Date（）格式）< / li> 
< li> ['title']< i>< u> string< / u>< / i>更改视图中显示的字段名称。< / li> 
< li> ['desc']< i>< u> string< / u>< / i>在编辑/创建视图中显示的说明。< / li> 
< li> ['readonly']< i>< u> boolean< / u>< / i> True可防止用户在编辑/创建表单中更改值。< / li> 
< li> ['type']< i>< u> string< / u>< / i>定义Form帮助程序使用的输入类型（示例'password'）< / li> 
< li> ['options']< i>< u>数组< / u>< / i>定义下拉列表的字符串选项列表。< / li> 
< li> ['editor']< i>< u> boolean< / u>< / i>如果设置为True，则会显示此字段的WYSIWYG编辑器。< / li> 
< li> ['default']< i>< u> string< / u>< / i>创建表单的默认值。< / li> 
< / ul> 
< / li> 
< / ul> 
< / li> 
< / ul> 
  
结果：
 
 
 
 
 
 
 array ['fields'] array定义要通过框架显示的字段。 
 
 
 
 
 [fieldName] array定义字段的选项，或者仅在未应用数组时启用字段。 
 
 
 
 ['name']  string 覆盖字段名称（默认为数组键）
 
 
 '/'> （可选）如果字段是belongsTo关联值，则覆盖模型。
 
 
 ['width']  string 定义分页视图的字段宽度。示例为100px或auto
 
 
 ['align']  string 分页视图（左，右，中心）的对齐类型
 
 
 ['format']  string 分页字段的格式化选项。选项包括（'currency'，'nice'，'niceShort'，'timeAgoInWords'或有效的Date（）格式）
 
 
 ['title'] 更改视图中显示的字段名称。
 
 
 ['desc'] 字符串 
 
 
 ['readonly']  boolean  True可防止用户更改编辑/创建表单中的值。 i>定义Form帮助器使用的输入类型（示例'password'）
 
 
 ['options']  
 
 
 ['editor']  boolean 如果设置为True，则会显示此字段的WYSIWYG编辑器。 ['default']  string 创建表单的默认值。
 
 
 
 
 
 
 
 
如果你想要它看起来花哨，有点Css它会使奇迹！ xd 
 
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 = array(
   'fields'=>array(
       'title'=>array('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: 


    

        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

                        
这篇关于在PHPDoc中文档数组选项的最佳方式？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！