Previous Up Next
@package phpDocumentor tags @property

@param

Document a function parameter

Gregory Beaver
Tag Documentation written by [email protected]
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:

  • $paramname if there is only one parameter

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

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:

  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.  * (notice how $foo_desc is NOT part of the actual function signature in the code, but still gets documented)
  51.  * @param string $foo 
  52.  * @param mixed $foo_desc optional description of foo
  53.  */
  54. function function3($foo)
  55. {
  56.    echo $foo;
  57.    if (func_num_args == 2)
  58.    {
  59.       echo 'Description: '.func_get_arg(1);
  60.    }
  61. }
  62.  
  63. /**
  64.  * Example of unlimited parameters.
  65.  * Returns a formatted var_dump for debugging purposes
  66.  * (since the recurrences of $v are not listed in the actual function signature in the code,
  67.  * you may wish to highlight they are "optional" in their description)
  68.  * @param string $s string to display
  69.  * @param mixed $v variable to display with var_dump()
  70.  * @param mixed $v,... unlimited OPTIONAL number of additional variables to display with var_dump()
  71.  */
  72. function fancy_debug($s,$v)
  73. {
  74.    print $s."<blockquote>\n";
  75.    var_dump($v);
  76.    if (func_num_args()>2)
  77.    {
  78.       for($i=2;$i<func_num_args();$i++)
  79.       {
  80.          $a = func_get_arg($i);
  81.          var_dump($a);
  82.          print "<br>\n";
  83.       }}
  84.    print "</blockquote>\n";
  85. }

Previous Up Next
@package phpDocumentor tags @property

Documentation generated on Mon, 05 Dec 2011 21:18:38 -0600 by phpDocumentor 1.4.4