phpDocumentor и ключевое слово @global - PullRequest
Новая
       5

phpDocumentor и ключевое слово @global

1 голос
/ 08 июля 2011

Правильно ли мое использование @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.

1 Ответ

1 голос
/ 08 июля 2011

На самом деле, ваша переменная $ instance не находится в глобальной области видимости, на основе этого кода ... она является локальной только для функции MySpecialClass :: display_template ().

Если вы хотите подчеркнуть на странице документации template.php, что для читателя есть что-то важное в отношении переменной $ instance, вы можете использовать тег @see в docblock на уровне файла template.php ( место, где у вас есть тег @global), чтобы указать читателю функцию MySpecialClass, которая устанавливает $ instance: 

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