Previous Up Next
@package phpDocumentor tags @property

@param

Document a function parameter

Gregory Beaver
Tag Documentation written by cellog@php.net
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

datatype should be a valid PHP type or "mixed", or 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:

  • $paramname if there is only one parameter

  • $paramname,... if the number of parameters is unlimited

phpDocumentor will display the optional description unmodified

Example

Here's an example:

  1. /**
  2.  * example of basic @param usage
  3.  * @param bool $baz 
  4.  * @return mixed 
  5.  */
  6. function function1($baz)
  7. {
  8.    if ($baz)
  9.    {
  10.       $a = 5;
  11.    } else
  12.    {
  13.       $a = array(1,4);
  14.    }
  15.    return $a;
  16. }
  17.  
  18. class class1
  19. {
  20.    /**
  21.     * example of documenting a method, and using optional description with @return
  22.     * @return string de-html_entitied string (no entities at all)
  23.     */
  24.    function bar($foo)
  25.    {
  26.       return strtr($foo,array_flip(get_html_translation_table(HTML_ENTITIES)));
  27.    }
  28. }
  29.  
  30. /**
  31.  * Example of documenting multiple possible datatypes for a given parameter
  32.  * @param bool|string $foo sometimes a boolean, sometimes a string (or, could have just used "mixed")
  33.  * @param bool|int $bar sometimes a boolean, sometimes an int (again, could have just used "mixed")
  34.  */
  35. function function2($foo, $bar)
  36. {
  37.    if (!$foo)
  38.    {
  39.       // definitely not a string, and not a boolean TRUE... could ONLY be a boolean FALSE
  40.    }
  41.  
  42.    if (!$bar)
  43.    {
  44.       // could ONLY be a boolean FALSE or an integer "0"
  45.    }
  46. }
  47.  
  48. /**
  49.  * Example of documenting undetermined function arguments
  50.  * @param string $foo 
  51.  * @param mixed $foo_desc optional description of foo
  52.  */
  53. function function3($foo)
  54. {
  55.    echo $foo;
  56.    if (func_num_args == 2)
  57.    {
  58.       echo 'Description: '.func_get_arg(1);
  59.    }
  60. }
  61.  
  62. /**
  63.  * Example of unlimited parameters.
  64.  * Returns a formatted var_dump for debugging purposes
  65.  * @param string $s string to display
  66.  * @param mixed $v variable to display with var_dump()
  67.  * @param mixed $v,... unlimited number of additional variables to display with var_dump()
  68.  */
  69. function fancy_debug($s,$v)
  70. {
  71.    print $s."<blockquote>\n";
  72.    var_dump($v);
  73.    if (func_num_args()>2)
  74.    {
  75.       for($i=2;$i<func_num_args();$i++)
  76.       {
  77.          $a = func_get_arg($i);
  78.          var_dump($a);
  79.          print "<br>\n";
  80.       }}
  81.    print "</blockquote>\n";
  82. }

Previous Up Next
@package phpDocumentor tags @property

Documentation generated on Sun, 30 Mar 2008 22:45:15 -0500 by phpDocumentor 1.4.2