Previous Up Next
@filesource phpDocumentor tags @ignore

@global

Document a global variable, or its use in a function/method

Gregory Beaver
Tag Documentation written by [email protected]
Copyright 2002, Gregory Beaver
(phpDocumentor 0.1+)
@global datatype $globalvariablename
@global datatype description

Description

Since there is no standard way to declare global variables, phpDocumentor requires that a @global tag be used in a docblock preceding a global variable's definition. To support previous usage of @global, there is an alternate syntax that applies to DocBlocks preceding a function, used to document usage of global variables. in other words, There are two usages of @global: definition and function usage.

phpDocumentor will not attempt to automatically parse out any global variables. Only one @global tag is allowed per global variable DocBlock. A global variable DocBlock must be followed by the global variable's definition before any other element or DocBlock occurs in the source, or an error will be raised.

datatype should be a valid PHP type or "mixed."

$varname should be the EXACT name of the global variable as it is declared in the source (use @name to change the name displayed by documentation)

The function/method @global syntax is used to document usage of global variables in a function, and MUST NOT have a $ starting the third word. The datatype will be ignored if a match is made between the declared global variable and a variable documented in the project.

phpDocumentor will check to see if the type specified is the name of a class that has been parsed. If so, it will make a link to that class as the type instead of just the type.

phpDocumentor will display the optional description unmodified

Example

Here's an example of documenting the definition of a global variable:

  1. /**
  2.  * example of incorrect @global declaration #1
  3.  * @global bool $GLOBALS['baz'] 
  4.  * @author blahblah
  5.  * @version -6
  6.  */
  7. include("file.ext");
  8. // error - element encountered before global variable declaration, docblock will apply to this include!
  9. $GLOBALS['baz'] = array('foo','bar');
  10.  
  11. /** example of incorrect @global declaration #2
  12.  * @global parserElement $_Element 
  13.  */
  14. /**
  15.  * error - this DocBlock occurs before the global variable definition and will apply to the function,
  16.  * ignoring the global variable completely
  17.  * /
  18. $_Element = new parserElement;
  19.  
  20. function oopsie()
  21. {
  22. ...
  23. }
  24.  
  25. /** example of correct @global declaration,
  26.  * even with many irrelevant things in between
  27.  * @global mixed $_GLOBALS["myvar"] 
  28.  */
  29. // this is OK
  30. if ($pre)
  31. {
  32.     $thisstuff = 'is fine too';
  33. }
  34. $_GLOBALS["myvar"] = array( "this" => 'works just fine');
  35.  
  36. /**
  37.  * example of using @name with @global
  38.  * the @name tag *must* have a $ in the name, or an error will be raised
  39.  * @global array $GLOBALS['neato'] 
  40.  * @name $neato
  41.  */
  42. $GLOBALS['neato'] = 'This variable\'s name is documented as $neato, and not as $GLOBALS[\'neato\']';

Here's an example of documenting the use of a global variable in a function/method:

  1. /**
  2.  * Used to showcase linking feature of function @global
  3.  */
  4. class test
  5. {
  6. }
  7.  
  8. /**
  9.  * @global test $GLOBALS['baz'] 
  10.  * @name $bar
  11.  */
  12. $GLOBALS['bar'] = new test
  13.  
  14. /**
  15.  * example of basic @global usage in a function
  16.  * assume global variables "$foo" and "$bar" are already documented
  17.  * @global bool used to control the weather
  18.  * @global test used to calculate the division tables
  19.  * @param bool $baz 
  20.  * @return mixed 
  21.  */
  22. function function1($baz)
  23. {
  24.    global $foo,$bar;
  25.    // note that this also works as:
  26.    // global $foo;
  27.    // global $bar;
  28.    if ($baz)
  29.    {
  30.       $a = 5;
  31.    } else
  32.    {
  33.       $a = array(1,4);
  34.    }
  35.    return $a;
  36. }

Previous Up Next
@filesource phpDocumentor tags @ignore

Documentation generated on Mon, 05 Dec 2011 21:52:10 -0600 by phpDocumentor 1.4.4