Comment Associative Array in PHP Documentor

Comment associative array in PHP Documentor

You can't document each key, but you can tell phpDocumentor what type it is.

You could do something like this:

/**
* Form the array like this:
* <code>
* $array = array(
* 'id' => 'foo', // the id
* 'class' => 'myClass', // the class
* );
*
* </code>
*
* @var array[string]string
*/
$array;

Best way to document Array options in PHPDoc?

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

PHPStorm + PHPdoc - can I type hint individual array element?

You can define the array keys in advance, then PHPStorm will suggest them (CTRL+space)

$my = array();
$my['qwe'] = '';
$my['asd'] = '';
$my['zxc'] = '';

$my['']// inside '' will be autosuggest

You can also use phpdoc (CTRL+Q):

/**
* keys:
* <pre>
* some_array (array)
* some_bool (boolean)
* some_double (double)
* some_nice_integer (integer)
* </pre>
* @return array
*/
public function toArray(){
// return some array
}

How to document an array of [type]?

From the documentation of phpDocumentor

The value represented by Type can be an array. The type MUST be defined following the format of one of the following options:

  1. unspecified, no definition of the contents of the represented array is given. Example: @return array

  2. specified containing a single type, the Type definition informs the reader of the type of each array element. Only one Type is then expected as element for a given array.

    Example: @return int[]

    Please note that mixed is also a single type and with this keyword it is possible to indicate that each array element contains any possible type.

  3. specified containing multiple types, the Type definition informs the reader of the type of each array element. Each element can be of any of the given types. Example: @return (int|string)[]

    Note
    many IDEs probably do not support this notation yet.

Is there a way for phpDoc to document an array of objects as a parameter?

New version of PHP doc support /** @var sometype[] */ syntax. Even more complicated: /** @var (sometype|othertype)[] */. http://www.phpdoc.org/docs/latest/guides/types.html#arrays
PHPStorm also support this syntax.

PHPDoc type hinting for array of objects?

Use:

/* @var $objs Test[] */
foreach ($objs as $obj) {
// Typehinting will occur after typing $obj->
}

when typehinting inline variables, and

class A {
/** @var Test[] */
private $items;
}

for class properties.

Previous answer from '09 when PHPDoc (and IDEs like Zend Studio and Netbeans) didn't have that option:

The best you can do is say,

foreach ($Objs as $Obj)
{
/* @var $Obj Test */
// You should be able to get hinting after the preceding line if you type $Obj->
}

I do that a lot in Zend Studio. Don't know about other editors, but it ought to work.



Related Topics



Leave a reply



Submit