Inline documentation improvements in wp-includes/link-template.php

[dustyf]

Functions in wp-includes/link-template.php are lacking @return statements and some that have @return lack descriptions. This includes:

• get_next_posts_page_link() - Lacks return description.
• next_posts() - Lacks @return
• get_next_posts_link() - Lacks return description.
• get_previous_posts_page_link() - Lacks @return
• previous_posts() - Lacks return description
• get_previous_posts_link - Lacks return description.

[colorful tones]

Added missing @return statements and descriptions

[dustyf]

Adding more doc updates for missing @return descriptions and one missing @param

[dustyf]

I was able to find a handful more docblocks that needed descriptions and one that lacked an @param for one of the parameters. The attached diff file includes the patches from colorful tones plus my additions.

[DrewAPicture]

Hi Damon and Dusty, thanks for the patches!

Just a few things to point out that I've adjusted in 30406.2.patch​:

• Since "link" is kind of a relative term -- especially in this file -- it's better to err on the side of specificity in saying "link URL" vs "link" as the latter implies an HTML-formatted link
• "HTML formatted" should be hyphenated
• Per core style, we generally don't use the work 'specified', so in most cases that became 'given'
• Return descriptions shouldn't align with @param descriptions, and also can't be optional :)

[DrewAPicture]

In 30628:

Add missing return descriptions for a variety of functions in wp-includes/link-template.php.

Props colorful-tones, dustyf.
See #30406.

[DrewAPicture]

This will likely span past our cutoff for 4.1, though the current commits on the ticket will still count for the 4.1 release cycle.

[DrewAPicture]

In 37213:

Docs: Use third-person singular verbs in DocBlock and hook doc summaries in wp-includes/link-template.php.

See #30406.

[DrewAPicture]

In 37252:

Docs: Properly notate optional parameters as such in a variety of DocBlocks in wp-includes/link-template.php.

See #30406.

[DrewAPicture]

In 37254:

Docs: Notate optional parameter defaults for a variety of function DocBlocks in wp-includes/link-template.php.

See #30406.

[DrewAPicture]

In 37258:

Docs: Notate more optional parameter defaults for a variety of function DocBlocks in wp-includes/link-template.php.

See #30406.

[DrewAPicture]

In 37259:

Docs: Capitalize URL – an acronym for Uniform Resource Locator – when used in the context of inline docs in wp-includes/link-template.php.

Fixes #30406.