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)
Here's an example:
/** * example of incorrect @global declaration #1 * @global bool $GLOBALS['baz'] * @author blahblah * @version -6 */ include("file.ext"); // error - element encountered before global variable declaration, docblock will apply to this include! $GLOBALS['baz'] = array('foo','bar'); /** example of incorrect @global declaration #2 * @global parserElement $_Element */ /** * error - this DocBlock occurs before the global variable definition and will apply to the function, * ignoring the global variable completely */ $_Element = new parserElement; function oopsie() { ... } /** example of correct @global declaration, * even with many irrelevant things in between * @global mixed $_GLOBALS["myvar"] */ // this is OK if ($pre) { $thisstuff = 'is fine too'; } $_GLOBALS["myvar"] = array( "this" => 'works just fine'); /** * example of using @name with @global * the @name tag *must* have a $ in the name, or an error will be raised * @global array $GLOBALS['neato'] * @name $neato */ $GLOBALS['neato'] = 'This variable\'s name is documented as $neato, and not as $GLOBALS[\'neato\']'; |
The alternate @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 display the optional description unmodified
Here's an example:
/** * example of basic @global usage in a function * assume global variables "$foo" and "$bar" are already documented * @global bool used to control the weather * @global integer used to calculate the division tables * @param bool $baz * @return mixed */ function function1($baz) { global $foo,$bar; // note that this works as: // global $foo; // global $bar; if ($baz) { $a = 5; } else { $a = array(1,4); } return $a; } |
Tag Documentation written by Gregory Beaver <cellog@users.sourceforge.net>
Copyright © 2002, Gregory Beaver