[解決済み] PHPDoc で Array オプションのドキュメントを作成するには?

質問

関数に渡されるArrayオプションのマルチツリー構造を説明する、読みやすく、理解しやすいドキュメントを書くのに苦労しています。

以下は配列構造の例です。

$arr = [
   'fields' => [
       'title' => [
           'name'     => 'Document.title',
           'format'   => 'string',
           'readonly' => true
       ]
   ]
];

上記の配列には多くのオプションが考えられますが、これはその構造を理解する関数のパラメータとして使用されます。

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

配列がどのように構成されるべきかを PHPDoc で文書化したいのですが、 正しい方法がわかりません。

今あるのはこんな感じです。

/**
 * 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文書が生成されたときに、それがあまりきれいにフォーマットされていないことです。さらに、上記が配列構造を明確に説明しているかどうかわかりません。

別の方法はありますか？

どのように解決するのですか？

表組みを追加するだけで、見栄えがよくなり、わかりやすくなる

/**
 * 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 scaffoldingによって表示されるフィールドを定義します。
  • [fieldName] 配列 フィールドのオプションを定義します。
    • ['name']（名前 文字列 フィールド名を上書きします（デフォルトは配列のキー）。
    • ['モデル'] 文字列 (オプション) フィールドが belongsTo に関連する値である場合、モデルをオーバーライドします。
    • ['width'] (幅) 文字列 paginateビューのためのフィールドの幅を定義します。例としては、"100px" または "auto"があります。
    • ['align'] (アライン) 文字列 paginateビューのアラインメントタイプ (左、右、中央)
    • ['フォーマット'] 文字列 paginateフィールドのフォーマットオプション。オプションには ('currency', 'nice', 'niceShort', 'timeAgoInWords' または有効な Date() フォーマット) が含まれます。
    • ['title']（タイトル 文字列 ビューに表示されるフィールド名を変更します。
    • ['desc'] を指定します。 文字列 edit/createビューに表示される説明文。
    • ['readonly']（読み取り専用 ブーリアン Trueにすると、編集/作成フォームでユーザーが値を変更することを防ぎます。
    • ['type'] (タイプ) 文字列 Formヘルパーで使われる入力タイプを定義します (例 'password')。
    • ['オプション'] 配列 ドロップダウンリストの文字列オプションのリストを定義します。
    • ['エディタ'] ブール型 Trueに設定すると、このフィールドにWYSIWYGエディタを表示します。
    • ['default']（デフォルト 文字列 createフォームのデフォルト値。

派手な感じにしたい場合は、CSSを少し使うと不思議な感じになりますよ。xd