phpDocumentor phpDocumentor
[ class tree: phpDocumentor ] [ index: phpDocumentor ] [ all elements ]
Prev Next
@param

@param

Document a function parameter

by Gregory Beaver
Tag Documentation written by cellog@php.net
Copyright 2002, Gregory Beaver
(phpDocumentor 0.1+)
@param datatype $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." 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 undetermined function arguments
  32.  * @param string $foo 
  33.  * @param mixed $foo_desc optional description of foo
  34.  */
  35. function function2($foo)
  36. {
  37.    echo $foo;
  38.    if (func_num_args == 2)
  39.    {
  40.       echo 'Description: '.func_get_arg(1);
  41.    }
  42. }
  43.  
  44. /**
  45.  * Example of unlimited parameters.
  46.  * Returns a formatted var_dump for debugging purposes
  47.  * @param string $s string to display
  48.  * @param mixed $v variable to display with var_dump()
  49.  * @param mixed $v,... unlimited number of additional variables to display with var_dump()
  50.  */
  51. function fancy_debug($s,$v)
  52. {
  53.    print $s."<blockquote>\n";
  54.    var_dump($v);
  55.    if (func_num_args()>2)
  56.    {
  57.       for($i=2;$i<func_num_args();$i++)
  58.       {
  59.          $a func_get_arg($i);
  60.          var_dump($a);
  61.          print "<br>\n";
  62.       }}
  63.    print "</blockquote>\n";
  64. }

Prev Up Next
@package phpDocumentor tags @return

Documentation generated on Tue, 24 Oct 2006 09:20:09 -0500 by phpDocumentor 1.3.1