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