@param
Document a function parameter
Gregory Beaver
Copyright 2002, Gregory Beaver
(phpDocumentor 0.1+)
@param
datatype
$paramname
description
@param
datatype1|datatype2
$paramname
description
Description
NOTE: as of 0.4.1, @param can document phpdoc.de-style, with optional $paramname
The datatype should be a valid PHP type (int, string, bool, etc), a class name for the type of object, or simply "mixed". Further, you can list multiple datatypes for a single parameter by delimiting them with the pipe (e.g. "@param int|string $p1"). You may document parameters listed or any optional paramters that will be parsed by standard PHP functions func_num_args()/get_func_arg(). Recommended name format for parameters listed with func_get_arg() is:
phpDocumentor will display the optional description unmodified.
Note that the $paramname,... will be shown in the output docs in both the parameter listing AND the function signature. If you are not indicating in the actual code that the parameter is optional (via "$paramname = 'a default value'"), then you should mention in the parameter's description that the parameter is optional.
Example
Here's an example:
/**
* example of basic @param usage
* @param bool $baz
* @return mixed
*/
function function1($baz)
{
if ($baz)
{
$a = 5;
} else
{
$a = array(1,4);
}
return $a;
}
class class1
{
/**
* example of documenting a method, and using optional description with @return
* @return string de-html_entitied string (no entities at all)
*/
function bar($foo)
{
}
}
/**
* Example of documenting multiple possible datatypes for a given parameter
* @param bool|string $foo sometimes a boolean, sometimes a string (or, could have just used "mixed")
* @param bool|int $bar sometimes a boolean, sometimes an int (again, could have just used "mixed")
*/
function function2($foo, $bar)
{
if (!$foo)
{
// definitely not a string, and not a boolean TRUE... could ONLY be a boolean FALSE
}
if (!$bar)
{
// could ONLY be a boolean FALSE or an integer "0"
}
}
/**
* Example of documenting undetermined function arguments
* (notice how $foo_desc is NOT part of the actual function signature in the code, but still gets documented)
* @param string $foo
* @param mixed $foo_desc optional description of foo
*/
function function3($foo)
{
echo $foo;
{
}
}
/**
* Example of unlimited parameters.
* Returns a formatted var_dump for debugging purposes
* (since the recurrences of $v are not listed in the actual function signature in the code,
* you may wish to highlight they are "optional" in their description)
* @param string $s string to display
* @param mixed $v variable to display with var_dump()
* @param mixed $v,... unlimited OPTIONAL number of additional variables to display with var_dump()
*/
{
print $s."<blockquote>\n";
{
{
print "<br>\n";
}}
print "</blockquote>\n";
}
Documentation generated on Mon, 05 Dec 2011 21:07:28 -0600 by phpDocumentor 1.4.4