@version [version] Provides the version number of a class or method
@author Author Name <author@email> The author of the current element
@copyright name date Documents copyright information
@package name of a package A group of related classes and functions
@subpackage sub-package under @package classes or functions
@todo Documents things that need to be done to the code at a later date
@deprecated [version] Documents a method as deprecated. also:@deprec
@since [version] Documents when a method was added to a class
@param int $para ... Documents a method/function parameter
@return int ... for function or methods explicitly returning
@throws InvalidArgumentException ... thrown by function / method
@global type $globalvarname ... for use in a function or method
@name $myvar ... An alias for a variable: ex: $GLOB['myvar'] to $myvar
@staticvar int $var A static variable in a function or class
@var string $prop A class property
@property int $getset ... allows you to label "magic" properties not otherwise obvious
@static Documents a static class or method
@abstract Documents an abstract class, class variable or method
@access [public|private|protected] For class element
@ignore Prevents the documentation of an element
@internal Private information for advanced developers
@link [URL] Displays a hyperlink to a URL in the documentation
@example /path/to/example location of an external saved example file
@see [URI|FQSEN] ... tag will show a link to related item
Say you have this:
$array['fields'] = []; # array Defines the feilds to be shown by scaffolding.
$array['fields'][fieldName] =[]; # 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.
$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.Here is a good way to document an array of options:
/**
* 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.
**/<?php
/**
*
* File description ... notice the inline link
* here: ({@link http://example.com/my/bar}) and non-inline:
*
* @link http://example.com/MyCategory/PackName/SubPack Docs here
*
* @category MyCategory (not so common)
* @package PackName
* @subpackage SubPack
* @version 1.0
* @author Jeff Russ <[email protected]>
* @copyright 2016 Jeff Russ
* @license GPL-2.0
*/
namespace PackageName\SomeClass;
/**
* Global variable declaration
*
* @global int $GLOB['_myvar']
* @name $myvar An alias for $GLOB['myvar']
*/
$GLOB['myvar'] = 6;
/** @ignore State why phpdoc should be ignoring this */
define("OS","Windows");
/**
* A sample function docblock. Note that in addition to mixed[] you can do
* unspecified with simply: array. Or int[] or (int|string)[].
*
* @param mixed[] $items An array of mixed type values
* @return int The static variable, modified
*
* @global string Document the use of $myvar
* @staticvar integer The global $staticvar is returned
*/
function count(array $items) {
static $staticvar = 7;
global $myvar;
return $staticvar;
}
/**
* ClassName - An example class, this is grouped with other classes
* in the "PackName" package and is part of "SubPack" subpackage
*
* @package PackName
* @subpackage SubPack
* @todo Documents things that need to be done to the code at a later date.
*
* @method void setString(string $my_param)
* @method string getString()
*/
class ClassName
{
/**
* @var string|null $name Description...
* @var string $more Description...
*/
protected $name = null;
protected $more = '';
/** @var string can omit prop name if there is only one*/
const MY_CONSTANT = 'whatever';
/**
* Description
*
* @var string
*/
const MY_CONSTANT = 'whatever';
/**
* setString Description
*
* @param string $my_param (default: 'test')
* @return void
*/
public function setString($my_param = 'test') { }
/**
* getString Description
*
* @return string the string
*/
public function getString($my_param = 'test') { }
}