phpdoc/docblock improvements cache.php - global variables

[hakre]

While going through source I stumbeled over docblocks in cache.php. Since I did something similar within some other parts of the core some time ago I wanted to evolve it a bit and went through the docblocks regarding global variable usage.

Please see it as a suggestion. I think the source pretty much speaks for itself. I've made this based on the documentation here:

​Document a global variable, or its use in a function/method (phpDocumentor Manual)

[hakre]

I actually need a core-devs statement on how to docblock-handle those globals. I would like to see that in, because my IDE does support code completition then an I think it will other developers as well.

[Denis-de-Bernardy]

new patch builds upon the existing one, and strips the global's initialization. imo that ought to be the job for wp_cache_init(), in case the variable is already initialized by a cache plugin.

[nacin]

Replying to Denis-de-Bernardy:

new patch builds upon the existing one, and strips the global's initialization. imo that ought to be the job for wp_cache_init(), in case the variable is already initialized by a cache plugin.

Doesn't look like you have that in your patch..

[nacin]

Ok, didn't see that you were pulling it out of the initial patch.

You can't include phpdoc inside of a function, it doesn't work. Other changes look okay though, but in order for @global to work, the global needs to be documented elsewhere. Otherwise you need to specify $GLOBALSvar?. The link in the ticket description explains this.

[hakre]

@var is an exception, it's used in inline comments for do type hinting in the editor / IDE. PDT for example has that.

[nacin]

Inline docs -- needs new patch.

[DrewAPicture]

[34225] added DocBlock-level @global comments for all of the functions/methods leveraging the $wp_object_cache global. Calling this fixed.