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. }