WordPress.tv: Add @param and @global keywords for some variables

[rushabh4486]

Documents need to improve.

[SergeyBiryukov]

Hi @rushabh4486, welcome to WordPress Meta Trac! Thanks for the patch.

Per WordPress' ​PHP Documentation Standards, @global tags are used to document globals in functions or methods. What's the benefit of adding @global tags right next to the global declarations in theme templates? Seems redundant, and none of the bundled themes do that.

[rushabh4486]

Replying to SergeyBiryukov:

Hi @rushabh4486, welcome to WordPress Meta Trac! Thanks for the patch.

Per WordPress' ​PHP Documentation Standards, @global tags are used to document globals in functions or methods. What's the benefit of adding @global tags right next to the global declarations in theme templates? Seems redundant, and none of the bundled themes do that.

What about @param tag?

@SergeyBiryukov

[SergeyBiryukov]

Replying to rushabh4486:

What about @param tag?

The change in functions.php looks good, though it would also be helpful to add a description, something like:

@param WP_Query $query Current query object.

[SergeyBiryukov]

#3232 was marked as a duplicate.

[rushabh4486]

Replying to SergeyBiryukov:

#3232 was marked as a duplicate.

Hello @SergeyBiryukov
What about 3134(1).patch?

[iandunn]

Hi @rushabh4486, thanks for your contribution here. Conforming to PHPDoc is a good thing to do. Compared to other tickets, though, this is a very low priority.

That doesn't mean that it won't be accepted one day, but properly prioritizing tickets helps us focus our time on what will make the biggest impact.

[iandunn]

Hi @rushabh4486, this should remain at lowest, per comment:16. Thanks :)

[mariovalney]

Hi @rushabh4486, this should remain at lowest because this is just documentation. And I guess it's better as a ​enhancement because the same reason.

You can check more information about Ticket Properties ​here. :)

[obenland]

In 6374:

WP.tv: Add docs for globals.

Also updates some existing docs.

Props rushabh4486 for initial patch.
Fixes #3134.