get_the_content() has undocumented globals

[slimndap]

get_the_content() is using several globals that are mentioned, but not explained in the docblock:

 * @global int   $page
 * @global int   $more
 * @global bool  $preview
 * @global array $pages
 * @global int   $multipage

It took me a while before I was able to understand what they are and where/when they are set.

[slimndap]

Same goes for setup_postdata() and WP_Query:: setup_postdata().

[goranseric]

Commented globals

[goranseric]

I have tested this and used ​https://codex.wordpress.org/Global_Variables as reference. First time commiter, so I hope it will be good to go :)

[DrewAPicture]

@goranseric Thanks for the patch, I'll take a look and let you know if any changes are needed.

Assigning the ticket to mark the good-first-bug as "claimed".

[DrewAPicture]

@goranseric In the case of descriptions for globals, we should be describing what the global represents at the initial point of access, rather than trying to be specific about what purpose they serve in the current context.

So for $multipage, for instance, it's truly an indicator for whether pagination is play. It's technically an integer, but treated as a boolean.

So a possible description for $multipage might be something like:

 * @global int $multipage Boolean indicator for whether multiple pages are in play.

In the case of $pages, what it really represents is an array of all pages. And so on with the others.

[goranseric]

@DrewAPicture thanks for pointing this out to me, and thanks for the example.
I have attached new descriptions according to your comments and also made comments more consistent to others in core.

Nice to see that we have a little freedom in expressing , I went quite stuffy :-D

[morganestes]

Updated patch to align global descriptions.

[slimndap]

Would it also be possible to mention at what point these globals are set? Currently, as a developer, it is really hard to debug get_the_content() because it is so hard to understand where these values are coming from.

[swissspidy]

I'm not sure about $preview right now, but most of them are set in WP_Query by setup_postdata(). We should get rid of most them though, see #36934.

[swissspidy]

In 38746:

Docs: Document global variables used by get_the_content().

Props goranseric, morganestes.
Fixes #37173.