PHPDoc does not seem to recognize global variables in output. What am I doing wrong?

问题

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.

回答1:

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

来源：https://stackoverflow.com/questions/12163292/phpdoc-does-not-seem-to-recognize-global-variables-in-output-what-am-i-doing-wr

标签

global-variables

phpdoc