本文介绍了PHPDoc似乎无法识别输出中的全局变量。我究竟做错了什么?的处理方法,对大家解决问题具有一定的参考价值,需要的朋友们下面随着小编来一起学习吧!

问题描述

在我的代码中有以下内容:

$ $ $ $ $ $ $ $ $ b $主数据库连接对象
*
* @global object $ GLOBALS ['db']
* @name $ db
* /
global $ db;

现在你会认为这足够了,但是当我运行phpdoc时,没有提及这个变量在文档或任何其他全局变量中的任何地方。是什么赋予了?这是直接出来的文档。为什么它不能识别并记录这个变量作为一个全局变量?作为第二个问题,看起来你应该能够引用函数中使用的全局变量而不需要重复这里给出的每一个函数的描述。这在理论上是正确的吗?如何使这项工作?



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

解决方案

以您的示例为例代码在哪里全局有效初始化:

$ $ $
$主数据库连接对象
*
* @global resource $ GLOBALS ['db']
* @name $ db
* /
$ GLOBALS ['db'] = getConnection(...);

请注意,在这里您需要使用格式@global datatype $ globalvariablename。还要注意,如果您使用$ GLOBALS ['db']需要与其他匹配,则这是您要包含@name $ globalvariablename标记的地方>代码中显示全局$ db的地方。相反,如果您只是在代码中使用$ db =而不是$ GLOBALS ['db'],那么@name标签会变得多余且不必要。至于我,我会选择使用$ GLOBALS ['db']在代码中,因此需要全局+名称标记,因为我希望全局变量在我的代码中非常明确可见(至少当我无法重构它们时;-))。

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

  / ** 
*我的方法使用全局
*
* @global资源通用数据库连接对象
* /
public function foo {
global $ db;

//在这里使用$ db连接
}

请注意这里的格式是@全局数据类型描述,这与上面的不同。另外,您不要 在这里放置@name标签。



在这里,phpDocumentor将识别代码本身中的global $ db行 ,并分别查找 有docblock'd全球本身的初始化。



我认为 必须存在这样的@global用法,以便您可以看到 >在文档中 - 后者表明您的文档化方法使用全局和前者,这样方法的文档就可以显示关于该特定全局的信息。

参考文献:

[1] - @global -



[2] - @name -


I have the following in my code

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

Now you would think that this would be sufficient, but when I run phpdoc, there is no mention of this variable anywhere in the documentation or any other global variable. What gives? This is straight out of the documentation. Why isn't it recognizing and recording this variable as a global?

As a secondary question, it seems you ought to be able to reference global variables used in functions without having to repeat the description given here in every single function it's used in. Is that correct in theory? How does one make that work?

Dunno. Phpdoc seems like a great tool in theory, but it just doesn't seem to like me.

解决方案

Taking your example as the code where the global is effectively initialized:

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

Note that here you need to use the format "@global datatype $globalvariablename". Also note that this is where you would include the "@name $globalvariablename" tag, if your use of "$GLOBALS['db']" needs to be matched to other places in the code that show "global $db". Instead, if you simply use "$db = " in the code rather than "$GLOBALS['db'], the @name tag becomes redundant and unnecessary. As for me, I would choose to use $GLOBALS['db'] in the code, and therefore need both global+name tags, just because I like to have globals be very explicitly visible in my code (at least when I can't refactor them away ;-) ).

Your use of the "global" keyword in your code example implies that you are actually inside a function/method, rather than at the global variable's initialization. In that case, your method's docblock needs this format of the global tag:

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

Note the format here is "@global datatype description", which is different than the one above. Also, you do not put a @name tag here.

Here, phpDocumentor will recognize the "global $db" line in the code itself, and look for where you separately have docblock'd the initialization of the global itself.

I think it is necessary for both such "@global" usages to exist in order for you to see anything in the docs -- the latter to show that your documented method uses a global, and the former so that the method's docs have information to show about that particular global.

References:

[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

这篇关于PHPDoc似乎无法识别输出中的全局变量。我究竟做错了什么?的文章就介绍到这了,希望我们推荐的答案对大家有所帮助,也希望大家多多支持!

09-12 04:36
查看更多