0

我的代码中有以下内容

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

现在你会认为这已经足够了，但是当我运行 phpdoc 时，文档中的任何地方都没有提到这个变量或任何其他全局变量。是什么赋予了？这直接来自文档。为什么它不将此变量识别并记录为全局变量？

作为第二个问题，您似乎应该能够引用函数中使用的全局变量，而不必在使用它的每个函数中重复此处给出的描述。这在理论上是否正确？如何使这项工作？

不知道。从理论上讲，Phpdoc 似乎是一个很棒的工具，但它似乎并不喜欢我。

4

1 回答 1

2

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

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

请注意，这里您需要使用格式“@global datatype $globalvariablename”。另请注意，如果您对“$GLO​​BALS['db']”的使用需要与代码中显示“global $db”的其他位置相匹配，您将在此处包含“@name $globalvariablename”标签。相反，如果你只是在代码中使用“$db =”而不是“$GLO​​BALS['db']，@name 标记就会变得多余且不必要。至于我，我会选择使用 $GLOBALS['db']在代码中，因此需要两个全局+名称标记，只是因为我喜欢让全局变量在我的代码中非常明确可见（至少当我无法重构它们时 ;-) ）。

您在代码示例中使用“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”行，并查找您在哪里分别对全局本身的初始化进行了 docblock。

我认为有必要同时存在这样的“@global”用法，以便您在文档中看到任何内容——后者表明您记录的方法使用全局，而前者表明该方法的文档有信息展示那个特定的全局。

参考：

[1] -- @global -- 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

于 2012-08-28T19:56:03.680 回答