PHPDoc似乎无法识别输出中的全局变量.我做错了什么

Question

我的代码中有以下内容

/**
 * The primary database connection object
 * 
 * @global object $GLOBALS['db']
 * @name $db
 */
global $db;

现在您可能认为这就足够了，但当我运行phpdoc时，文档中的任何地方或任何其他全局变量都没有提到这个变量。什么东西？这直接来自文档。为什么它不将这个变量识别并记录为全局变量？

作为第二个问题，你似乎应该能够引用函数中使用的全局变量，而不必在每个函数中重复这里给出的描述。这在理论上正确吗？如何做到这一点？

不。Phpdoc在理论上似乎是一个很好的工具，但它似乎不喜欢我。

Answer 1

以全局有效初始化的代码为例：

/**
 * the primary database connection object
 *
 * @global resource $GLOBALS['db']
 * @name $db
 */
$GLOBALS['db'] = getConnection(...);

请注意，这里需要使用"@global-datatype$globalvariablename"格式。还要注意的是，如果您对"$GLOBALS['db']"的使用需要与代码中显示"global$db"的其他位置相匹配，则会在此处包含"@name$globalvariablename"标记。相反，如果你在代码中简单地使用"$db="而不是"$GLOBALS[db']"，@name标记就会变得多余和不必要。对我来说，我会选择在代码中使用$GLOBALS[db''，因此需要两个global+name标记，因为我喜欢全局在我的代码中非常明显地可见（至少当我不能重构它们时；-））。

在代码示例中使用"global"关键字意味着您实际上在函数/方法内部，而不是在全局变量的初始化处。在这种情况下，您的方法的docblock需要以下格式的全局标记：

/**
 * my method that uses a global
 *
 * @global resource the universally available database connection object
 */
public function foo {
    global $db;
    // do stuff here that uses the $db connection
}

请注意，这里的格式是"@global datatype description"，与上面的格式不同。此外，您可以而不是在此处放置@name标记。

在这里，phpDocumentor将识别代码本身中的"global$db"行，并分别查找有文档阻止全局初始化的地方。

我认为有必要存在这两个这样的"@global"用法，以便您在文档中看到任何东西——后者表明您的文档化方法使用了全局，前者使方法的文档具有有关该特定全局的信息。

参考文献：

[1] --@全局--http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.global.pkg.html

[2] --@name--http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.name.pkg.html