Is my use of @global correct in the following case?
// File: my_special_class.php
<?php
...
class MySpecialClass {
function display_template() {
// Following variable will be available from context of 'template.php':
$instance = array( 'title' => 'Test Page' );
include('template.php');
}
}
// File: template.php
<?php
/**
* Template for ...
*
* @copyright Me
* @version 1
*
* @global array $instance Template instance parameters.
*/
?>
<h1><?php echo $instance['title']; ?></h1>
Is there a standard way of documenting this?
It is primarily a reminder for those reading the code, but it would be useful if this information was also present under phpDocumentor generated documentation.
Actually, your $instance variable is not in the global scope, based on this code... it is local to the MySpecialClass::display_template() function only.
If you want to highlight, from the template.php documentation page, that there is something of significance to the reader with regard to the $instance variable, you could use the @see tag in template.php's file-level docblock (the location that you currently have the @global tag) to point the reader to the MySpecialClass's function that sets $instance:
<?php
/**
* Template for ...
*
* @copyright Me
* @version 1
*
* @see MySpecialClass::display_template() to see how $instance is populated
*/
?>
<h1><?php echo $instance['title']; ?></h1>