_get_cron_lock is missing PHPdoc

[mordauk]

The function definition for _get_cron_lock() is missing PHPDoc.

[valendesigns]

Should we be completely changing the description here? I'm thinking the original text was a bit more descriptive then "Gets the cron lock". Granted the original text is not much better. Maybe something like...

/**
 * Returns the uncached `doing_cron` transient.
 *
 * @since  3.3
 * @return string|false
 */

[DrewAPicture]

I think either way, we need a DocBlock, so +1 for adding one.

Since this an underscore-prefixed function, that typically denotes a private or utility function, in which case we'd skip parsing. Unless somebody can make a convincing argument for why this should have a place in the code reference, I'd recommend adding the @ignore tag to the DocBlock.

[valendesigns]

I agree, this doesn't need to be included in the code reference. However, something to consider would be removing the function all together. The only place core uses it is in wp-cron.php. It could easily be turned into a variable. Patch 31646.1.diff​ should demonstrate what I mean. Obviously it's to late for 4.2, but still worth mentioning. The last patch will have to suffice for now.

[SergeyBiryukov]

Replying to valendesigns:

The only place core uses it is in wp-cron.php. It could easily be turned into a variable.

I think it's a function and not a variable in order to make sure we get a fresh value for each check, see [18659].

[valendesigns]

Replying to SergeyBiryukov:

I think it's a function and not a variable in order to make sure we get a fresh value for each check, see [18659].

It looks like it was actually in the foreach statement, and then was moved into a function for ease of use. I don't think it becoming a function actually solved the issue of getting a fresh value, just it being moved out of that loop did.

[valendesigns]

I could be wrong, it's just what I saw from first glance. Unless, it needs a fresh value in the loop every time it asks for the cron lock.

[SergeyBiryukov]

Replying to valendesigns:

I could be wrong, it's just what I saw from first glance. Unless, it needs a fresh value in the loop every time it asks for the cron lock.

Yes, that's my understanding. Some actions may take a long time to run, so we need to check the fresh value on each iteration to see if the lock still belongs to the current process.

[SergeyBiryukov]

So the refactoring is not needed here, let's just add missing docs.

[valendesigns]

Replying to SergeyBiryukov:

So the refactoring is not needed here, let's just add missing docs.

Thanks for the explanation, that makes perfect sense.

[valendesigns]

@ignore added to docblock

[SergeyBiryukov]

Let's also add a sentence about the uncached doing_cron transient, as you suggested in comment:2.

[valendesigns]

Patch added. Let me know if you want the text changed at all. Cheers!

[mordauk]

Looks good to me.

[DrewAPicture]

In 31804:

Add a missing DocBlock for the core utility function _get_cron_lock().

Props mordauk, valendesigns.
Fixes #31646.