@global

(phpDocumentor 1.1+ )

@global --  document a global variable, or its use in a function/method

Description

@global datatype $varname

-or-

@global datatype 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)

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