Make WordPress Core

Opened 5 years ago

Closed 5 years ago

#45445 closed defect (bug) (fixed)

Cron-related documentation incorrectly uses `@see` syntax in a number of places

Reported by: coffee2code's profile coffee2code Owned by: peterwilsoncc's profile peterwilsoncc
Milestone: 5.1 Priority: low
Severity: minor Version: 5.1
Component: Cron API Keywords: has-patch
Focuses: docs Cc:


Cron-related hooks committed and slated for 5.1 were introduced with docblocks that incorrectly use the @see syntax to reference hooks and functions. The incorrect uses were of the format {@see pre_unschedule_event}. This is ambiguous as to what is being referenced. Currently, the Code Reference would only try to link each of these to a function, assuming such a function exists.

In the case of hooks (which were the most common occurrences of this problem), the syntax should be {@see 'pre_unschedule_event'} (note the single quotes).

In the case of functions, something like {@see wp_get_schedules} should be {@see wp_get_schedules()}. However, it is not necessary to use the @see syntax when referencing functions, classes, or methods since they can be inferred (and are inferred and auto-linked by the Code Reference).

The documentation standards mention the use of @see for referencing hooks, but could stand to be more explicit about not needing to be used for functions, classes, or class methods.

These were introduced mostly from [43540] (but also [43050] and [43608]).

Related: #32656.

The attached patch fixes the hook references and removes explicit referencing of a few functions (all of which were added in the aforementioned commits).

Attachments (2)

45445.diff (4.4 KB) - added by coffee2code 5 years ago.
Patch mentioned in ticket.
45445.2.diff (4.9 KB) - added by peterwilsoncc 5 years ago.

Download all attachments as: .zip

Change History (5)

5 years ago

Patch mentioned in ticket.

#1 @peterwilsoncc
5 years ago

  • Milestone changed from Awaiting Review to 5.1
  • Owner set to peterwilsoncc
  • Status changed from new to accepted

Thanks @coffee2code, I've added this to the 5.1 milestone and will follow up once the branch re-opens and action this as part of updating the @since tags.

#3 @peterwilsoncc
5 years ago

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

In 44374:

Docs: Correct @see syntax for Cron API changes.

Fixes documentation errors introduced in [43540], [43050] and [43608].

Props coffee2code.
Fixes #45445.

Note: See TracTickets for help on using tickets.