phpDocumentor 和@global 关键字

Question

在以下情况下我对@global 的使用是否正确？

// 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>

有标准的记录方式吗？

这主要是对那些阅读代码的人的提醒，但如果这些信息也出现在 phpDocumentor 生成的文档下，将会很有用。

Answer 1

实际上，您的 $instance 变量不在全局范围内，基于此代码...它仅对 MySpecialClass::display_template() 函数是本地的。

如果你想在 template.php 文档页面中强调 $instance 变量对读者来说很重要，你可以在 template.php 的文件级文档块中使用 @see 标签（您当前拥有 @global 标记的位置）将阅读器指向设置 $instance 的 MySpecialClass 函数：

<?php
/**
 * Template for ...
 *
 * @copyright Me
 * @version 1
 *
 * @see MySpecialClass::display_template() to see how $instance is populated
 */
?>
<h1><?php echo $instance['title']; ?></h1>