在 PHPDoc 中记录数组选项的最佳方式?

2021-12-21 00:00:00 php cakephp phpdoc

我正在努力编写可读且易于理解的文档，以描述传递给函数的数组选项的多树结构.

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) { ... }

我想记录如何在 PHPDoc 中构建数组，但我不确定正确的方法是什么.

I'd like to document how the array should be structured in PHPDoc, but I'm not sure what the correct approach is.

这是我现在拥有的.

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

我的问题是当生成 HTML 文档时，它的格式不是很好.另外，我不确定上面是否清楚地解释了数组结构.

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.

有替代方法吗?

推荐答案

只要加入一些制表，就会好看又容易理解

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

嵌套列表方法:

<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>

结果:

  • array['fields'] array 定义脚手架显示的字段.
    • [fieldName] array 定义字段的选项，或者如果未应用 array，则仅启用该字段.
      • ['name'] string 覆盖字段名(默认是数组键)
      • ['model'] string(可选)如果该字段是相关联的值，则覆盖模型.
      • ['width'] string 定义分页视图的字段宽度.例如100px"或auto"
      • ['align'] string 分页视图的对齐类型(左、右、中)
      • ['format'] string 分页字段的格式选项.选项包括('currency'、'nice'、'niceShort'、'timeAgoInWords' 或有效的 Date() 格式)
      • ['title'] string 更改视图中显示的字段名称.
      • ['desc'] string 编辑/创建视图中显示的描述.
      • ['readonly'] boolean True 可防止用户更改编辑/创建表单中的值.
      • ['type'] string 定义表单助手使用的输入类型(例如'password')
      • ['options'] array 定义下拉列表的字符串选项列表.
      • ['editor'] boolean 如果设置为 True 将显示此字段的 WYSIWYG 编辑器.
      • ['default'] string 创建表单的默认值.
      • 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.

          如果你想让它看起来很花哨，用一点 CSS 会创造奇迹！xd

          If you want it to look fancy, with a bit of Css it will make wonders! xd

相关文章