WordPress.org

Make WordPress Core

Opened 3 years ago

Closed 20 months ago

#30406 closed task (blessed) (fixed)

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

Reported by: dustyf Owned by: DrewAPicture
Milestone: 4.6 Priority: normal
Severity: normal Version:
Component: Permalinks Keywords:
Focuses: docs Cc:

Description

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.

Attachments (3)

30406.patch (1.7 KB) - added by colorful tones 3 years ago.
Added missing @return statements and descriptions
30406.2.diff (13.3 KB) - added by dustyf 3 years ago.
Adding more doc updates for missing @return descriptions and one missing @param
30406.2.patch (13.2 KB) - added by DrewAPicture 3 years ago.

Download all attachments as: .zip

Change History (16)

@colorful tones
3 years ago

Added missing @return statements and descriptions

@dustyf
3 years ago

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

#1 @dustyf
3 years ago

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.

#2 @dustyf
3 years ago

  • Keywords has-patch added

#3 @DrewAPicture
3 years ago

  • Milestone changed from Awaiting Review to 4.1
  • Version 4.0 deleted

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 :)

#4 @DrewAPicture
3 years ago

In 30628:

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

Props colorful-tones, dustyf.
See #30406.

#5 @DrewAPicture
3 years ago

  • Keywords has-patch removed
  • Milestone changed from 4.1 to Future Release

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.

#6 @chriscct7
2 years ago

  • Keywords needs-patch added
  • Owner set to drew
  • Status changed from new to assigned

#7 @DrewAPicture
2 years ago

  • Owner changed from drew to DrewAPicture

#8 @DrewAPicture
20 months ago

In 37213:

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

See #30406.

#9 @DrewAPicture
20 months ago

In 37252:

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

See #30406.

#10 @DrewAPicture
20 months ago

In 37254:

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

See #30406.

#11 @DrewAPicture
20 months ago

In 37258:

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

See #30406.

#12 @DrewAPicture
20 months ago

  • Keywords needs-patch removed
  • Milestone changed from Future Release to 4.6
  • Type changed from defect (bug) to task (blessed)

#13 @DrewAPicture
20 months ago

  • Resolution set to fixed
  • Status changed from assigned to closed

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.

Note: See TracTickets for help on using tickets.