在PHPDoc中记录数组选项的最佳方式是什么？
在PHPDoc中记录数组选项的最佳方式是什么？
提问于 2013-03-14 23:56:58
我正在努力编写可读且易于理解的文档，这些文档描述了传递给函数的数组选项的多树结构。
下面是一个数组结构示例。
$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文档时，它的格式不是很好。此外，我不确定上面的内容是否清楚地解释了数组结构。
有没有其他方法？
回答 7
Stack Overflow用户
发布于 2016-04-22 17:25:23
我是这样做的：
/**
* 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应该是什么。
Stack Overflow用户
发布于 2018-06-26 05:42:17
我写了一个plugin for phpstorm，它允许像这样指定键：
(基本上只是@siannone格式的一个稍微严格的版本)
/**
* @param array $arr = [
* 'fields' => [ // Defines the feilds to be shown by scaffolding
* $anyKey => [
* 'name' => 'sale', // Overrides the field name (default is the array key)
* 'model' => 'customer', // (optional) Overrides the model if the field is a belongsTo associated value.
* 'width' => '100px', // Defines the width of the field for paginate views. Examples are "100px" or "auto"
* 'align' => 'center', // Alignment types for paginate views (left, right, center)
* 'format' => 'nice', // Formatting options for paginate fields. Options include ('currency','nice','niceShort','timeAgoInWords' or a valid Date() format)
* 'title' => 'Sale', // Changes the field name shown in views.
* 'desc' => 'A deal another person that results in money', // The description shown in edit/create views.
* 'readonly' => false, // True prevents users from changing the value in edit/create forms.
* 'type' => 'password', // Defines the input type used by the Form helper
* 'options' => ['option1', 'option2'], // Defines a list of string options for drop down lists.
* 'editor' => false, // If set to True will show a WYSIWYG editor for this field.
* 'default' => '', // The default value for create forms.
* ],
* ],
* ]
*/
public static function processForm($arr)
{
$fieldName = 'sale';
$arr['fields'][$fieldName][''];
}
它还允许指定@return密钥：
/**
* @return array [
* 'success' => true,
* 'formObject' => new Form,
* 'errors' => [],
* ]
*/
public static function processForm($arr);
Stack Overflow用户
发布于 2013-03-15 00:29:49
你能使用对象而不是数组吗？这将使文档记录变得容易。
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) {...}页面原文内容由Stack Overflow提供。腾讯云小微IT领域专用引擎提供翻译支持
原文链接：
https://stackoverflow.com/questions/15414103
复制相关文章
相似问题