Лучший способ документировать параметры массива в PHPDoc?

Я изо всех сил пытаюсь написать читаемую и понятную документацию, описывающую многоуровневую структуру для параметров Array, которые передаются функции.

Вот пример структуры массива.

$arr = array( 'fields'=>array( 'title'=>array('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 Определяет поля, которые будут отображаться с помощью лесов.
- [fieldName] array Определяет параметры для поля или просто включает поле, если массив не применяется.
  - ['name'] string Переопределяет имя поля (по умолчанию используется массив)
  - Строка ['model'] (необязательно) Переопределяет модель, если поле принадлежит принадлежит связанному значению.
  - ['width'] string Определяет ширину поля для представлений с разбивкой по страницам. Примерами являются «100px» или «auto»,
  - ['align'] string Типы выравнивания для просмотра страниц (слева, справа, в центре)
  - ['format'] string Параметры форматирования полей paginate. Варианты включают («валюта», «хороший», «niceShort», «timeAgoInWords» или действительный формат Date ())
  - ['title'] string Изменяет имя поля, отображаемое в представлениях.
  - Строка ['desc'] Описание показано в edit / create views.
  - ['readonly'] boolean True запрещает пользователям изменять значение в формах edit / create.
  - ['type'] string Определяет тип ввода, используемый помощником формы (пример «пароль»)
  - ['options'] array Определяет список параметров строки для выпадающих списков.
  - ['editor'] boolean Если установлено значение True, будет отображаться редактор WYSIWYG для этого поля.
  - ['default'] string Значение по умолчанию для создания форм.

Если вы хотите, чтобы он выглядел причудливым, с небольшим количеством Css он будет творить чудеса! XD

Слишком поздно для вечеринки, но вот как я это делаю:

 /** * Class constructor. * * @param array $params Array containing the necessary params. * $params = [ * 'hostname' => (string) DB hostname. Required. * 'databaseName' => (string) DB name. Required. * 'username' => (string) DB username. Required. * 'password' => (string) DB password. Required. * 'port' => (int) DB port. Default: 1433. * 'sublevel' => [ * 'key' => (\stdClass) Value description. * ] * ] */ public function __construct(array $params){}

Подумайте, что это довольно чисто и легко понять, какими должны быть $params .

Можете ли вы использовать объекты вместо массивов? Это упростит документацию.

 class Field { /** * The name of the thing. * @var string */ protected $name; protected $model; protected $width; //... public function getName() {...} public function setName() {...} //... } class FieldList implements SomeKindOfIterator { /** * Some fields. * @var Field[] */ protected $fields = array(); /** * ... */ public function push(Field $field) { $this->fields[] = $field; } //... }

Затем вы можете использовать подсказку типа, где требуется класс.

 /** * Do something. * @param FieldList $field_list The field. */ function doSomething(FieldList $field_list) {...}

Я вроде как лучше:

  * @param array $doc * 'type'=>Doc::MY_DOC_TYPE, * 'created'=>$now, * 'modified'=>$now

Я просто вставляю код, откуда он инициализируется, быстро и легко.

Синтаксис Markdown для Object Notation (MSON) может быть лучшим выбором.

пример

 /** * @param array $config * + app (string, required) - app directory name * + view (string, required) - view directory name * + type (enum[string]) - site type * + pc - PC version * + wap - mobile version * + other - other, default value * + table_prefix (string) - database table prefix */

AS это чисто отображение, а не директива и должно сохранять форматирование пространства внутри документов, я был бы склонен идти на удобочитаемость с отступом, а не с стенкой символов:

  * array['fields'] array Defines the feilds 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 assoicated 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.

Хотя использование фактического определения массива PHP с отступом даже более чистое